AI Content Drop Discovery API

openapi: 3.2.0
info:
  title: AI Content Drop Discovery API
  version: 2.7.0
  summary: Generate AI video and images programmatically, and read AI Content Drop's public content as plain text, markdown, or XML.
  description: 'The public REST API of https://aicontentdrop.com — generate AI video and images programmatically on your own account.


    **Authentication**: an API key created in your dashboard (Settings → Integrations). Keys look like `acd_live_…` and are sent as `Authorization: Bearer`. The index and the model catalogue need no key at all; everything that touches an account or spends credits does.


    **Generation is submit-and-poll**: POST returns a record immediately with status `generating`, then GET /v1/videos/{id} until `completed`. Credits are flat per model and are only charged on success — safety blocks, provider failures, and timeouts cost nothing.


    **Rate limits**: 120 requests/minute. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`; a 429 additionally sends `Retry-After` (seconds).


    **Errors** are always structured JSON, never HTML. /v1 read endpoints return `{"error": {"code", "message"}}`; the generation endpoints (shared with the website) return `{"error": "", "code"?: ""}`.


    **Versioning**: the version is in the URL path (`/v1`). A breaking change ships as a new path segment; the previous version keeps working for at least 180 days and is announced with `Deprecation` and `Sunset` response headers (RFC 9745 / RFC 8594) before it is removed. Policy: https://aicontentdrop.com/developers#versioning


    **Other protocols over the same capabilities**: MCP (Streamable HTTP) at POST /mcp, manifest at /.well-known/mcp.json; A2A (JSON-RPC 2.0) at POST /a2a; NLWeb at POST /ask. The read-only text/markdown content surface is documented separately at https://aicontentdrop.com/openapi-content.json.


    **Batch**: `POST /v1/batch` runs up to 20 read operations in one request; `POST /v1/models/cost` quotes up to 50 model/quantity pairs. Generation is never batched — see the endpoint description for why.


    **Sandbox**: send `X-Sandbox: true` on either generation endpoint, with or without a key, to rehearse the call for free.


    **GraphQL**: the same data is served at `POST https://aicontentdrop.com/graphql` with open introspection, Relay connections, and typed errors. SDL at https://aicontentdrop.com/graphql/schema.graphql, documentation at https://aicontentdrop.com/docs/graphql.'
  contact:
    name: AI Content Drop support
    email: support@aicontentdrop.com
    url: https://aicontentdrop.com/contact
  license:
    name: Content usage terms
    url: https://aicontentdrop.com/terms-of-use
servers:
- url: https://aicontentdrop.com
  description: Production
tags:
- name: Discovery
  description: Unauthenticated index and capability discovery
paths:
  /v1:
    get:
      tags:
      - Discovery
      operationId: getApiIndex
      summary: Machine-readable API index
      description: 'Unauthenticated index of the /v1 surface: endpoint list, authentication scheme, documentation URL, and the MCP endpoint. The starting point for an agent that only knows the domain.'
      x-openai-isConsequential: false
      responses:
        '200':
          description: API index
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  version:
                    type: string
                  documentation:
                    type: string
                    format: uri
                  authentication:
                    type: string
                  endpoints:
                    type: object
                    additionalProperties:
                      type: string
                  mcp:
                    type: object
                    properties:
                      endpoint:
                        type: string
                        format: uri
                      transport:
                        type: string
        '429':
          description: Rate limited. Read Retry-After (header) or error.retry_after_seconds (body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      security: []
  /.well-known/agent-skills/index.json:
    get:
      tags:
      - Discovery
      operationId: getAgentSkillsIndex
      summary: Importable agent skills index
      description: 'Agent Skills Discovery index (v0.2.0 schema): downloadable SKILL.md guides with SHA-256 digests, covering AI video prompt craft, 30-second UGC ad scripting, and AI video model selection. Artifacts live under /agent-skills/{name}.md.'
      x-openai-isConsequential: false
      responses:
        '200':
          description: The published agent skills, each with a URL and a content digest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSkillsIndex'
        '429':
          description: Rate limited. Read Retry-After (header) or error.retry_after_seconds (body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      security: []
  /ask:
    post:
      tags:
      - Discovery
      operationId: askNaturalLanguage
      summary: Natural-language query (NLWeb)
      description: 'Ask a natural-language question about the model catalogue or our published guides and get Schema.org-shaped JSON results. Implements the NLWeb /ask convention (github.com/microsoft/NLWeb). Read-only, no API key, keyword-routed (no LLM call), 60 requests/minute. Use it for discovery; use POST /v1/generate/video to actually generate. Set `prefer.streaming: true` (or send `Accept: text/event-stream`) for an SSE response with `start`, `result`, and `complete` events.'
      x-openai-isConsequential: false
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  maxLength: 500
                  description: The question, in natural language
                  example: which video models cost under 15 credits?
      responses:
        '200':
          description: Ranked results
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - _meta
                - query
                - results
                properties:
                  _meta:
                    type: object
                    required:
                    - response_type
                    - version
                    properties:
                      response_type:
                        type: string
                        enum:
                        - model_catalogue
                        - articles
                        description: Which answer set the query was routed to
                      version:
                        type: string
                        description: NLWeb contract version
                      site:
                        type: string
                      protocol:
                        type: string
                      documentation:
                        type: string
                        format: uri
                  query:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      required:
                      - url
                      - name
                      - site
                      - score
                      - description
                      properties:
                        url:
                          type: string
                          format: uri
                        name:
                          type: string
                        site:
                          type: string
                        score:
                          type: number
                          description: Relevance, 0-100
                        description:
                          type: string
                        schema_object:
                          type: object
                          description: Schema.org representation of the item
                          additionalProperties: true
                  capabilities:
                    type: object
                    additionalProperties: true
            text/event-stream:
              schema:
                type: string
                description: 'SSE frames: event: start | result | complete'
        '400':
          description: The query was missing or unusable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      tags:
      - Discovery
      operationId: askNaturalLanguageGet
      summary: Natural-language query (NLWeb, query-string form)
      description: Identical to POST /ask, with the question supplied as the `query` query-string parameter. Provided because some agent HTTP clients cannot send a request body on a discovery call.
      x-openai-isConsequential: false
      security: []
      parameters:
      - name: query
        in: query
        required: true
        description: The question, in natural language
        schema:
          type: string
          maxLength: 500
        example: which video models cost under 15 credits?
      responses:
        '200':
          description: Ranked results
          content:
            application/json:
              schema:
                type: object
                required:
                - _meta
                - query
                - results
                properties:
                  _meta:
                    type: object
                    required:
                    - response_type
                    - version
                    properties:
                      response_type:
                        type: string
                        enum:
                        - model_catalogue
                        - articles
                        description: Which answer set the query was routed to
                      version:
                        type: string
                        description: NLWeb contract version
                      site:
                        type: string
                      protocol:
                        type: string
                      documentation:
                        type: string
                        format: uri
                  query:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      required:
                      - url
                      - name
                      - site
                      - score
                      - description
                      properties:
                        url:
                          type: string
                          format: uri
                        name:
                          type: string
                        site:
                          type: string
                        score:
                          type: number
                          description: Relevance, 0-100
                        description:
                          type: string
                        schema_object:
                          type: object
                          description: Schema.org representation of the item
                          additionalProperties: true
                  capabilities:
                    type: object
                    additionalProperties: true
        '400':
          description: The query was missing or unusable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RateLimitReset:
      description: Seconds until the current window resets
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed in the current window (120/minute on /v1)
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
  schemas:
    AgentSkill:
      type: object
      required:
      - name
      - type
      - description
      - url
      properties:
        name:
          type: string
        type:
          type: string
          enum:
          - skill-md
        description:
          type: string
        url:
          type: string
          format: uri
        digest:
          type: string
          description: sha256:… of the skill document, so a client can cache and detect changes.
    Error:
      type: object
      required:
      - error
      description: Every failure on the agent-facing surfaces (/v1, /graphql, /ask, /agent, /mcp) uses this envelope, on every status code. An HTML error page from these paths is a bug.
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this, never on the message text.
              enum:
              - invalid_request
              - invalid_json
              - payload_too_large
              - unauthorized
              - unauthenticated
              - invalid_client
              - forbidden
              - not_found
              - unknown_endpoint
              - unknown_model
              - method_not_allowed
              - unsupported_operation
              - unsupported_identity_type
              - missing_query
              - idempotency_conflict
              - insufficient_credits
              - safety_rejected
              - rate_limited
              - query_too_large
              - operation_failed
              - provider_error
              - internal_error
            message:
              type: string
              description: Human-readable explanation that names the failing field or resource, and what to do next.
            retry_after_seconds:
              type: integer
              minimum: 1
              description: Present on 429. Mirrors the Retry-After header. Wait this long before retrying; retrying sooner extends the window.
            documentation:
              type: string
              format: uri
              description: URL explaining this class of error.
            field:
              type: string
              description: 'Present on validation failures: the request field at fault.'
          additionalProperties: true
      examples:
      - error:
          code: rate_limited
          message: Rate limit exceeded. Wait 34 seconds and retry.
          retry_after_seconds: 34
          documentation: https://aicontentdrop.com/docs/rate-limits
    RateLimitError:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: 429. Read Retry-After (header) or error.retry_after_seconds (body) and back off; they carry the same number.
    AgentSkillsIndex:
      type: object
      required:
      - skills
      description: Agent Skills Discovery 0.2.0 index.
      properties:
        $schema:
          type: string
          format: uri
        skills:
          type: array
          items:
            $ref: '#/components/schemas/AgentSkill'
  responses:
    RateLimited:
      description: Rate limited. Read Retry-After (header) or error.retry_after_seconds (body) — they carry the same number — and wait that long. Retrying sooner extends the window rather than shortening it.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
    InternalError:
      description: Unexpected failure on our side. Retry once; nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: acd_live_…
      description: 'API key created at https://aicontentdrop.com/settings/integrations (any account, free tier included). Sent as `Authorization: Bearer acd_live_…`. Keys are shown once at creation and may carry a daily credit ceiling.'
externalDocs:
  description: Developer documentation, versioning and deprecation policy
  url: https://aicontentdrop.com/docs/versioning
x-api-version: '2026-08-24'
x-versioning:
  strategy: url-path
  current: v1
  version_header: API-Version
  deprecation_policy: https://aicontentdrop.com/docs/versioning
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link; rel="deprecation"
  minimum_notice_days: 180
  breaking_changes: Ship at a new path (/v2). /v1 response shapes are additive only.