> ## Documentation Index
> Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a pitch report

> 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.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/pitches
openapi: 3.1.0
info:
  title: AthenaHQ 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: Basics
    description: Core API operations for managing websites and prompts
  - name: Metrics
    description: Metrics and analytics endpoints for tracking AI visibility
  - name: Billing
    description: Billing and credits endpoints for managing usage
  - name: Team Management
    description: Endpoints for managing team members and invitations
  - name: Groups
    description: Endpoints for managing groups of websites
  - name: Content
    description: >-
      Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL
      prompt breakdowns.
  - name: Pitch Workspace
    description: >-
      Endpoints for accessing pitch workspace reports — org-scoped pitch runs
      with competitors, prompts, attributes, and aggregate metrics.
  - name: Knowledge Base
    description: >-
      Endpoints for reading the brand Knowledge Base — approved brand facts and
      the pillars that organize them.
paths:
  /api/v1/pitches:
    post:
      tags:
        - Pitch Workspace
      summary: Create a pitch report
      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.
      operationId: createPitch
      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.
      security:
        - apiKey: []
components:
  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).

````