# Context Engine

Source: https://recoupable.dev/docs/api-reference/context/operate

Ingest, read, or compile context briefs

## POST /api/context

Full OpenAPI specification: https://recoupable.dev/docs/spec/context.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup Context Engine",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/context": {
      "post": {
        "operationId": "contextOperation",
        "summary": "Ingest, read, or compile context briefs",
        "description": "Coverage note: this reference describes a subset of the current Context Engine action catalog. Additional actions are being reconciled in mono#329; this page is not a complete capability inventory. Save reusable music context, read progress, or compile a task-specific evidence brief. This reference documents the ingestion, read, brief, save_brief and read_brief actions of the shared HTTP/MCP operation. Brief compilation combines up to ten completed or partial requests in one authorized workspace, reuses saved evidence without provider or model calls, and returns bounded Markdown plus the selected input versions. Creative direction prioritizes lyrics and artwork; playlist pitching prioritizes catalog/audio metadata. Shared artist evidence appears once, with coverage reported separately for each request. Briefs are evidence packets, not generated creative concepts or finished outreach. Inspect readiness, request_coverage and gaps. The brief action is read-only; use save_brief with the same inputs and an idempotency_key to freeze the server-compiled output, then read_brief with its brief_id to retrieve it without recompilation. A newer document revision marks the snapshot superseded without rewriting it. Withdrawn/unavailable evidence, cancelled requests, or removed subject scope withhold the payload. Saving rechecks current evidence before committing. Apply the companion snapshot migration before using save_brief/read_brief. Ingestion dispatches a durable workflow; retry the same input and idempotency key after dispatch failure.",
        "security": [
          {
            "ApiKey": []
          },
          {
            "BearerAuth": []
          }
        ],
        "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,
                        "description": "Bounds selected evidence JSON and rendered Markdown independently. Does not cap the entire response, which also contains coverage and manifests. Documents are omitted whole to fit; omissions appear as coverage gaps."
                      },
                      "additional_request_ids": {
                        "type": "array",
                        "maxItems": 9,
                        "default": [],
                        "items": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "description": "Additional saved requests in the same selected workspace. Duplicate IDs are read once. Every request must be completed or partial; unavailable, cancelled, or inaccessible requests reject the operation."
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "action",
                      "request_id",
                      "purpose",
                      "idempotency_key"
                    ],
                    "properties": {
                      "action": {
                        "type": "string",
                        "const": "save_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,
                        "description": "Bounds selected evidence JSON and rendered Markdown independently. Does not cap the entire response, which also contains coverage and manifests. Documents are omitted whole to fit; omissions appear as coverage gaps."
                      },
                      "additional_request_ids": {
                        "type": "array",
                        "maxItems": 9,
                        "default": [],
                        "items": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "description": "Additional saved requests in the same selected workspace. Duplicate IDs are read once. Every request must be completed or partial; unavailable, cancelled, or inaccessible requests reject the operation."
                      },
                      "idempotency_key": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "pattern": "^[A-Za-z0-9._:-]+$",
                        "description": "Identifies one exact compiled output. Identical output reuses the saved record; different output with this key returns a conflict. After context updates, use read_brief for the old copy or a new key for a new snapshot."
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "action",
                      "brief_id"
                    ],
                    "properties": {
                      "action": {
                        "type": "string",
                        "const": "read_brief"
                      },
                      "brief_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "organization_id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "Optional organization that owns the private context. Current membership is checked."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "twoSongBrief": {
                  "summary": "Compile creative direction from two saved songs",
                  "value": {
                    "action": "brief",
                    "request_id": "11111111-1111-4111-8111-111111111111",
                    "additional_request_ids": [
                      "22222222-2222-4222-8222-222222222222"
                    ],
                    "purpose": "creative_direction",
                    "max_characters": 12000
                  }
                },
                "saveBrief": {
                  "summary": "Save a playlist-pitch brief",
                  "value": {
                    "action": "save_brief",
                    "request_id": "11111111-1111-4111-8111-111111111111",
                    "purpose": "playlist_pitch",
                    "idempotency_key": "pitch-v1"
                  }
                },
                "readBrief": {
                  "summary": "Read an exact saved brief",
                  "value": {
                    "action": "read_brief",
                    "brief_id": "33333333-3333-4333-8333-333333333333"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record."
          },
          "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."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```