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

# Context Engine

> Metadata pilot; release only after companion database/API deployments. Saves Spotify track, release and credited artist metadata for reuse. The MCP context tool uses the same operations. No paid enrichment runs yet: lyrics, audio analysis, artwork interpretation and artist research are reported as gaps. Briefs select saved evidence and do not generate creative concepts. Inspect readiness and missingTopics before using them. Ingest dispatches a durable workflow; retry the same input and idempotency key after dispatch failure. Private context is scoped to the authenticated account or authorized organization.



## OpenAPI

````yaml api-reference/openapi/context.json POST /api/context
openapi: 3.1.0
info:
  title: Recoup Context Engine
  version: 0.1.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/context:
    post:
      summary: Ingest, read, or select context
      description: >-
        Metadata pilot; release only after companion database/API deployments.
        Saves Spotify track, release and credited artist metadata for reuse. The
        MCP context tool uses the same operations. No paid enrichment runs yet:
        lyrics, audio analysis, artwork interpretation and artist research are
        reported as gaps. Briefs select saved evidence and do not generate
        creative concepts. Inspect readiness and missingTopics before using
        them. Ingest dispatches a durable workflow; retry the same input and
        idempotency key after dispatch failure. Private context is scoped to the
        authenticated account or authorized organization.
      operationId: contextOperation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - action
                    - url
                    - idempotency_key
                  properties:
                    action:
                      type: string
                      const: ingest
                    organization_id:
                      type: string
                      format: uuid
                      description: >-
                        Optional organization that owns the private context.
                        Current membership is checked.
                    url:
                      type: string
                      format: uri
                      description: >-
                        Spotify track URL. Albums, playlists and YouTube
                        ingestion are not enabled in this pilot.
                    idempotency_key:
                      type: string
                      minLength: 1
                      maxLength: 128
                      pattern: ^[A-Za-z0-9._:-]+$
                      description: >-
                        Stable key for retrying the same input without duplicate
                        work.
                    topics:
                      type: array
                      minItems: 1
                      maxItems: 10
                      items:
                        type: string
                        enum:
                          - release_metadata
                          - artist_metadata
                          - catalog_metadata
                          - lyrics
                          - song_summary
                          - artwork_branding
                          - artist_research
                          - artist_brand
                          - era
                          - video_narrative
                    direction:
                      type: string
                      maxLength: 4000
                      description: >-
                        Stored customer direction. Metadata extraction does not
                        interpret it as source facts.
                - type: object
                  additionalProperties: false
                  required:
                    - action
                    - request_id
                  properties:
                    action:
                      type: string
                      const: read
                    organization_id:
                      type: string
                      format: uuid
                      description: >-
                        Optional organization that owns the private context.
                        Current membership is checked.
                    request_id:
                      type: string
                      format: uuid
                - type: object
                  additionalProperties: false
                  required:
                    - action
                    - request_id
                    - purpose
                  properties:
                    action:
                      type: string
                      const: brief
                    organization_id:
                      type: string
                      format: uuid
                      description: >-
                        Optional organization that owns the private context.
                        Current membership is checked.
                    request_id:
                      type: string
                      format: uuid
                    purpose:
                      type: string
                      enum:
                        - creative_direction
                        - playlist_pitch
                    max_characters:
                      type: integer
                      minimum: 1000
                      maximum: 32000
                      default: 12000
      responses:
        '200':
          description: >-
            Read returns request. Brief returns purpose, readiness, documents,
            characters, missingTopics, guidance and gaps. Documents include
            saved result/version references and source citations.
        '202':
          description: >-
            Saved ingestion request; inspect request.status and use read to
            poll. Existing completed/partial requests return without provider
            work.
        '400':
          description: Invalid input
        '401':
          description: Authentication required
        '409':
          description: >-
            Operation failed, access unavailable, input/key conflict, or request
            not found. Retry ingestion with the same idempotency key after
            correcting the cause.
      security:
        - ApiKey: []
        - BearerAuth: []
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer

````