AthenaHQ SEO Recommendations API

openapi: 3.2.0
info:
  title: AthenaHQ SEO Recommendations 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: SEO Recommendations
paths:
  /api/v1/seo/recommendations:
    post:
      operationId: seoRecommendations.submit
      summary: Submit SEO recommendations
      description: Submit one draft or public HTTPS page for asynchronous SEO and AI-search recommendations. The website's organization must have the seo_recommendations entitlement in Autumn, and the caller must have website content administration access. Missing entitlement returns 403; an unavailable entitlement check returns 500 without creating a job. Queued work is checked again before analysis. Reuse request_id with identical input for retries; changed input returns 409. A website may have 1,000 outstanding jobs, with up to four active analyses and 16 across all websites. The website submit ceiling is 120 requests/minute, subject to the organization-wide API budget (default 60 requests/minute shared by submissions, polling and other API calls). Honor Retry-After on 429. Pace submissions and reserve request budget for polling a bounded subset of jobs; do not poll an entire backlog every poll_after_seconds. Polling never starts another analysis.
      responses:
        '202':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                  contract_version:
                    enum:
                    - seo-recommendations/v1
                    type: string
                  poll_after_seconds:
                    type: integer
                required:
                - job_id
                - status
                - contract_version
                - poll_after_seconds
        '400':
          description: 'Bad Request: validation failed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: 'Rate limited: honor Retry-After before retrying with the same request ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                website_id:
                  type: string
                request_id:
                  type: string
                source:
                  anyOf:
                  - type: object
                    properties:
                      kind:
                        enum:
                        - draft
                        type: string
                      title:
                        type: string
                      meta_description:
                        type: string
                      markdown:
                        type: string
                    required:
                    - kind
                    - title
                    - meta_description
                    - markdown
                  - type: object
                    properties:
                      kind:
                        enum:
                        - url
                        type: string
                      url:
                        type: string
                    required:
                    - kind
                    - url
                target_queries:
                  type: array
                  items:
                    type: string
                locale:
                  type: string
                local_context:
                  type: string
              required:
              - website_id
              - request_id
              - source
      tags:
      - SEO Recommendations
  /api/v1/seo/recommendations/{job_id}:
    get:
      operationId: seoRecommendations.get
      summary: Get SEO recommendation job
      description: Read a saved job with website content view access (viewer or higher). Results can contain evidence from submitted drafts. A completed result contains source-grounded recommendations, source_digest, token usage and warnings. Dollar cost is explicitly unavailable. Pending jobs wait for worker capacity; queued time does not expire an analysis. A failed worker returns a structured error; submit a new request_id to retry. Poll a bounded subset of jobs and back off while status remains pending; polling shares the organization-wide API request budget.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                  created_at:
                    type: string
                  completed_at:
                    anyOf:
                    - type: string
                    - type: 'null'
                  result:
                    anyOf:
                    - type: object
                      properties:
                        contract_version:
                          enum:
                          - seo-recommendations/v1
                          type: string
                        source_digest:
                          type: string
                        recommendations:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              priority:
                                type: string
                                enum:
                                - high
                                - medium
                                - low
                              category:
                                type: string
                                enum:
                                - seo
                                - aio
                              title:
                                type: string
                              change:
                                type: string
                              evidence:
                                type: string
                              heading_path:
                                type: array
                                items:
                                  type: string
                            required:
                            - id
                            - priority
                            - category
                            - title
                            - change
                            - evidence
                            - heading_path
                        usage:
                          type: object
                          properties:
                            input_characters:
                              type: integer
                            input_tokens:
                              anyOf:
                              - type: integer
                              - type: 'null'
                            output_tokens:
                              anyOf:
                              - type: integer
                              - type: 'null'
                            provider_cost_usd:
                              anyOf:
                              - type: number
                              - type: 'null'
                            cost_status:
                              enum:
                              - unavailable
                              type: string
                          required:
                          - input_characters
                          - input_tokens
                          - output_tokens
                          - provider_cost_usd
                          - cost_status
                        warnings:
                          type: array
                          items:
                            type: string
                      required:
                      - contract_version
                      - source_digest
                      - recommendations
                      - usage
                      - warnings
                    - type: 'null'
                  error:
                    anyOf:
                    - type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                      required:
                      - code
                      - message
                    - type: 'null'
                required:
                - job_id
                - status
                - created_at
                - completed_at
                - result
                - error
        '400':
          description: 'Bad Request: validation failed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: 'Rate limited: honor Retry-After before retrying with the same request ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      - name: website_id
        in: query
        required: true
        schema:
          type: string
      tags:
      - SEO Recommendations
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).