AthenaHQ Pitch Workspace API

openapi: 3.2.0
info:
  title: AthenaHQ Pitch Workspace API
  description: AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
- url: https://api.athenahq.ai
  description: Production server
security:
- apiKey: []
tags:
- name: Pitch Workspace
  description: Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics.
paths:
  /api/v1/pitches:
    post:
      tags:
      - Pitch Workspace
      summary: Create a pitch report
      operationId: createPitch
      description: Generate a Pitch Workspace report from a public website URL. Requires a global organization API key, Pitch Workspace entitlement, and available pitch allowance. Returns a durable pitch ID while research runs. Poll GET /api/v1/pitches/{pitch_id} until pitch.status is completed or failed. The report URL is accessible to anyone holding it. Each admitted request consumes one pitch, including attempts that fail during generation. Retrying the same organization and Idempotency-Key with the same normalized input reuses the pitch; different input returns 409. Use a new key to deliberately request a fresh snapshot. Generation does not send email.
      security:
      - apiKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
        description: Stable identifier for one logical request. Preserve it on retries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - website_url
              properties:
                website_url:
                  type: string
                  maxLength: 2000
                  example: https://example.com
                country:
                  type: string
                  maxLength: 100
                  default: United States
                language:
                  type: string
                  maxLength: 100
                  default: English
      responses:
        '202':
          description: Accepted, or the existing result for an idempotent retry. Generation may take several minutes.
          content:
            application/json:
              schema:
                type: object
                required:
                - pitch_id
                - status
                - report_url
                properties:
                  pitch_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - processing
                    - completed
                    - failed
                  report_url:
                    type: string
                    format: uri
        '400':
          description: Invalid body, URL or missing Idempotency-Key.
        '401':
          description: Missing or invalid API key.
        '403':
          description: Global organization key, Pitch Workspace entitlement or pitch allowance required.
        '404':
          description: The report for this request was deleted.
        '409':
          description: Idempotency-Key already used with different input.
        '429':
          description: Rate limit or three concurrent reports exceeded. Honor Retry-After.
        '500':
          description: Admission could not be confirmed. Retry with the same Idempotency-Key promptly; contact support if unresolved.
    get:
      tags:
      - Pitch Workspace
      summary: List Pitches
      description: 'Returns all non-deleted pitch workspace reports for the calling organization, ordered by creation date (newest first). Pitches are org-level resources and are not scoped to a single website.


        Requires a **global (organization-scoped) API key**. Website-scoped keys are rejected with `403 Forbidden`.'
      operationId: listPitches
      security:
      - apiKey: []
      responses:
        '200':
          description: Successful response with the list of pitches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pitches:
                    type: array
                    items:
                      $ref: '#/components/schemas/PitchSummary'
                required:
                - pitches
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — a website-scoped API key was used. Pitches are org-level resources; use a global API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Forbidden: global API key required'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/pitches/{pitch_id}:
    get:
      tags:
      - Pitch Workspace
      summary: Get Pitch Report
      description: 'Returns a single pitch report by ID, including the company metadata, generated prompts, tracked competitors, brand and competitor attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).


        Requires a **global (organization-scoped) API key**. Website-scoped keys are rejected with `403 Forbidden`. Returns `404 Not Found` if the pitch does not exist, has been deleted, or belongs to a different organization.'
      operationId: getPitch
      security:
      - apiKey: []
      parameters:
      - name: pitch_id
        in: path
        description: The UUID of the pitch to retrieve.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful response with the full pitch report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PitchReport'
        '400':
          description: Bad request — invalid `pitch_id` format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid pitch ID format
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — a website-scoped API key was used. Pitches are org-level resources; use a global API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Forbidden: global API key required'
        '404':
          description: Pitch not found in the calling organization, or has been deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Pitch not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
    PitchReport:
      type: object
      description: Full pitch report payload returned by `GET /api/v1/pitches/{pitch_id}`.
      required:
      - pitch
      - competitors
      - prompts
      - attributes
      - sources
      - metrics
      properties:
        pitch:
          $ref: '#/components/schemas/PitchSummary'
        competitors:
          type: array
          items:
            $ref: '#/components/schemas/PitchCompetitor'
          description: Competitors tracked on the pitch, with mention counts and sentiment.
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/PitchPrompt'
          description: Prompts generated for the pitch.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/PitchAttribute'
          description: Positive and negative attributes extracted from the pitch's responses, for both the target company and its competitors.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/PitchSource'
          description: Top 10 citing domains across the pitch's responses, ordered by mention count.
        metrics:
          $ref: '#/components/schemas/PitchMetrics'
    PitchSummary:
      type: object
      description: A pitch workspace report — org-scoped, returned in lists without the heavy report payload.
      required:
      - id
      - company_name
      - company_url
      - company_description
      - status
      - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the pitch.
          example: 123e4567-e89b-12d3-a456-426614174000
        company_name:
          type: string
          description: Display name of the company the pitch was created for.
          example: Acme Inc
        company_url:
          type: string
          description: The company website domain (without protocol).
          example: acme.com
        company_description:
          type: string
          description: Short description of the company captured at pitch creation time.
          example: Acme Inc sells durable industrial widgets to manufacturers.
        status:
          type: string
          enum:
          - draft
          - processing
          - completed
          - failed
          description: Current state of the pitch run. `processing` means the workflow is still generating prompts and responses; `completed` means the report is ready; `failed` means the run errored.
          example: completed
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp (UTC) for when the pitch was created.
          example: '2026-05-22T15:04:05.000Z'
        country:
          type: string
          nullable: true
          description: Target country for the pitch, or `null` if no country was set.
          example: United States
        language:
          type: string
          nullable: true
          description: Target language for the pitch, or `null` if no language was set.
          example: en
        type:
          type: string
          enum:
          - pitch_workspace
          - landing_page
          nullable: true
          description: Pitch variant. `pitch_workspace` is the standard pitch report; `landing_page` is generated from a landing page URL. `null` for legacy pitches predating the field.
          example: pitch_workspace
    PitchMetrics:
      type: object
      description: Aggregate metrics computed across the pitch's AI responses.
      required:
      - total_responses
      - brand_mentions
      - sentiment_score
      - response_rate
      properties:
        total_responses:
          type: integer
          description: Total number of AI responses collected for this pitch.
          example: 120
        brand_mentions:
          type: integer
          description: Number of responses in which the target company was mentioned.
          example: 64
        sentiment_score:
          type: integer
          description: Average sentiment across mentioning responses, expressed as an integer percent from 0 to 100. `positive` counts as 1, `neutral` as 0.5, and `negative` as 0; the average is then scaled to a percent. `0` when there are no brand mentions.
          minimum: 0
          maximum: 100
          example: 72
        response_rate:
          type: integer
          description: Share of responses that mentioned the target company, expressed as an integer percent from 0 to 100 (`brand_mentions / total_responses`).
          minimum: 0
          maximum: 100
          example: 53
    PitchPrompt:
      type: object
      description: A prompt generated for a pitch and used to query AI models.
      required:
      - id
      - prompt
      - type
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the pitch prompt.
          example: 22222222-3333-4444-5555-666666666666
        prompt:
          type: string
          description: The prompt text used for generation.
          example: What are the best industrial widget manufacturers?
        type:
          type: string
          description: Prompt category. Common values include `discovery` and `high_intent`; other values may be present depending on the pitch generator version.
          example: discovery
    PitchSource:
      type: object
      description: A top citing source (root domain) referenced across the pitch's AI responses.
      required:
      - domain
      - mentions
      properties:
        domain:
          type: string
          description: Root domain of the citing source. Google Places citations are surfaced as `google.com (Google Places)` to distinguish them from regular `google.com` citations.
          example: wikipedia.org
        mentions:
          type: integer
          description: Number of pitch source rows attributed to this domain.
          example: 18
    PitchCompetitor:
      type: object
      description: A competitor tracked on a pitch, with aggregate mention and sentiment stats across the pitch's responses.
      required:
      - id
      - name
      - url
      - mentions
      - sentiment
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the pitch competitor row.
          example: 11111111-2222-3333-4444-555555555555
        name:
          type: string
          description: Competitor display name.
          example: Competitor Co
        url:
          type: string
          description: Competitor website (without protocol).
          example: competitor.com
        mentions:
          type: integer
          description: Number of pitch responses where this competitor was mentioned.
          example: 42
        sentiment:
          type: integer
          description: Average sentiment across mentions, expressed as an integer percent from 0 to 100. `positive` mentions count as 1, `neutral` as 0.5, and `negative` as 0; the average is then scaled to a percent. `0` when the competitor has no mentions.
          minimum: 0
          maximum: 100
          example: 67
    PitchAttribute:
      type: object
      description: An attribute (positive or negative trait) extracted from pitch responses, applied to either the target company or its competitors.
      required:
      - id
      - attribute_name
      - attribute_type
      - applies_to
      - count
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the pitch attribute.
          example: 33333333-4444-5555-6666-777777777777
        attribute_name:
          type: string
          description: The attribute label.
          example: Reliable delivery
        attribute_type:
          type: string
          enum:
          - positive
          - negative
          description: Whether the attribute is a positive trait or a negative trait.
          example: positive
        applies_to:
          type: string
          enum:
          - target
          - competitors
          description: Whether the attribute describes the target company (`target`) or one of the tracked competitors (`competitors`).
          example: target
        count:
          type: integer
          description: How many pitch responses mentioned this attribute.
          example: 12
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api).