openapi: 3.0.3
info:
  title: AEO Registry AI API
  description: |
    Read-only API providing structured data for AI assistants and search engines. 
    Data is for visibility purposes only - no resale or repackaging without permission. 
    Each AEO page is available as clean HTML with an optional JSON mirror for integrators.
  version: 1.0.0
  contact:
    name: AEO Registry Support
    email: support@aeoregistry.com
    url: https://aeoregistry.com
  license:
    name: AEO Registry Terms
    url: https://aeoregistry.com/terms
  termsOfService: https://aeoregistry.com/terms

servers:
  - url: https://aeoregistry.com/api
    description: Production server

paths:
  /ai.json:
    get:
      summary: Get structured data for a single business
      description: Returns JSON-LD structured data for a single AEO page, optimized for AI consumption.
      parameters:
        - name: slug
          in: query
          description: The business slug (e.g., 'big-tuna-solutions')
          required: true
          schema:
            type: string
            example: big-tuna-solutions
        - name: org_id
          in: query
          description: Alternative: The organization ID
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response with JSON-LD structured data
          headers:
            ETag:
              description: Entity tag for caching (5 minute TTL)
              schema:
                type: string
            Last-Modified:
              description: Last modification timestamp
              schema:
                type: string
                format: date-time
            X-Terms:
              description: Terms of service reminder
              schema:
                type: string
                example: Data for visibility only. No resale/repackaging without permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIOutput'
        '304':
          description: Not modified (client has current version)
        '400':
          description: Bad request - missing required parameters
        '404':
          description: AEO page not found or feature not enabled
        '429':
          description: Rate limit exceeded - 60 requests per minute per IP
        '500':
          description: Internal server error
      options:
        summary: CORS preflight request
        responses:
          '200':
            description: CORS preflight successful

  /ai.ndjson:
    get:
      summary: Get structured data for multiple businesses (bulk)
      description: Returns NDJSON (newline-delimited JSON) stream with structured data for multiple AEO pages. Perfect for AI assistants that need bulk data access.
      parameters:
        - name: slugs
          in: query
          description: Comma-separated list of business slugs
          required: true
          schema:
            type: string
            example: big-tuna-solutions,storecaptainio,catscradle-media
        - name: limit
          in: query
          description: Maximum number of businesses to return (default: 10)
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
      responses:
        '200':
          description: Successful response with NDJSON stream
          headers:
            X-Terms:
              description: Terms of service reminder
              schema:
                type: string
                example: Data for visibility only. No resale/repackaging without permission.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: Newline-delimited JSON, each line is a complete AIOutput object
        '400':
          description: Bad request - missing slugs or too many requested
        '404':
          description: No AEO pages found or feature not enabled
        '429':
          description: Rate limit exceeded - 60 requests per minute per IP
        '500':
          description: Internal server error
      options:
        summary: CORS preflight request
        responses:
          '200':
            description: CORS preflight successful

components:
  schemas:
    AIOutput:
      type: object
      description: Structured data output optimized for AI consumption
      properties:
        "@context":
          type: string
          description: JSON-LD context
          example: https://schema.org
        "@graph":
          type: array
          description: Array of structured data entities
          items:
            $ref: '#/components/schemas/StructuredDataEntity'
        version:
          type: string
          description: API version
          example: 1.0.0
        generatedAt:
          type: string
          format: date-time
          description: Timestamp when the data was generated
        slug:
          type: string
          description: Business slug (only present in NDJSON output)
          example: big-tuna-solutions
      required:
        - "@context"
        - "@graph"
        - version
        - generatedAt

    StructuredDataEntity:
      type: object
      description: A single structured data entity containing only public, read-only data
      properties:
        "@type":
          type: string
          description: Schema.org type
          enum:
            - Organization
            - WebSite
            - WebPage
            - FAQPage
            - LocalBusiness
            - Product
            - Service
            - ProfessionalService
            - SoftwareApplication
        "@id":
          type: string
          description: Unique identifier for the entity
          format: uri
        name:
          type: string
          description: Public name of the entity
        description:
          type: string
          description: Public description of the entity
        url:
          type: string
          format: uri
          description: Public URL of the entity
        sameAs:
          type: array
          description: Public social media and website links
          items:
            type: string
            format: uri
        address:
          type: object
          description: Public business address (if available)
        mainEntity:
          type: object
          description: Reference to the main entity (Organization, Service, etc.)
      required:
        - "@type"
        - "@id"
      additionalProperties: false

tags:
  - name: AI Data
    description: Endpoints for AI assistants and search engines

externalDocs:
  description: AEO Registry Documentation
  url: https://aeoregistry.com