> ## Documentation Index > Fetch the complete documentation index at: https://docs.corti.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a context > Returns the context's metadata together with its `tasks`, oldest first. Each task carries its full message `history`; the user's prompt for a task is the `ROLE_USER` message within that task's history (there is no separate top-level message list). ## OpenAPI ````yaml /agentic/auto-generated-openapi-v2.yml get /v2/agentic/contexts/{contextId} openapi: 3.1.0 info: title: Corti Agent API v2 version: 2.0.0 summary: Manage agents and converse with them over the A2A v1.0 protocol. description: > Version 2 of the Corti Agents REST API. ## What's new in v2 - **Unified `connectors`** — a single, flat, discriminated array replaces the v1 split between `experts`, `mcpServers`, and sub-agents. The envelope is extensible: new connector kinds (`a2a`, `openapi`, `custom`) slot in behind the `type` discriminator without breaking changes. - **Clean CRUD verbs** — `POST` creates, `GET` fetches/lists, `PATCH` performs a *true* partial update, `DELETE` removes. v1's PATCH was effectively a PUT. - **First-class metadata** — `visibility`, `model`, `lifecycle` (now a body field, not a query param), and free-form `labels`. ## A2A v1.0 only The conversational surface speaks **A2A protocol version `1.0` exclusively** (both the `JSONRPC` and `HTTP+JSON` bindings). The deprecated v0.3 binding from v1 is intentionally not carried forward. Per A2A §3.6, clients MUST send the `A2A-Version` header (`Major.Minor`, e.g. `1.0`) on every request to the `/a2a/*` surface, or supply it as the `A2A-Version` query parameter. This surface implements `1.0` only; an absent header is treated as `1.0`. Patch versions MUST NOT be sent. The server echoes the negotiated version in the `A2A-Version` response header. ## Partial updates (PATCH) `PATCH` uses **JSON Merge Patch** semantics (RFC 7386), served under the `application/merge-patch+json` media type: - **Omit a field** → left unchanged. - **`null`** → cleared / reset to its default. - **Arrays** (e.g. `connectors`) → *replaced wholesale*, never merged. To mutate a single connector without replacing the whole array, use the `/connectors` sub-resource endpoints. ## Streaming (Server-Sent Events) The streaming A2A surfaces — `message/stream`, `tasks/subscribe`, and the streaming JSON-RPC methods — respond with `text/event-stream`. The `text/event-stream` media type carries a sequence of Server-Sent Events; the attached schema describes a single event frame. Every event's `data` field is a string carrying a JSON document (`contentMediaType: application/json`); `contentSchema` declares the parsed payload (`StreamResponse` for the `HTTP+JSON` binding, `JSONRPCResponse` for the `JSONRPC` binding). The optional `id` field carries the SSE event id used for resumption via the `Last-Event-ID` request header. contact: name: Corti API Support url: https://corti.ai email: support@corti.ai license: name: Proprietary url: https://corti.ai/terms termsOfService: https://corti.ai/terms servers: - url: https://api.{env}.corti.app description: Corti regional API gateway variables: env: default: eu enum: - eu - us description: Deployment region. security: - bearerAuth: [] tenantHeader: [] tags: - name: Agents description: Create, read, update, and delete agents. - name: Agent Card description: A2A-compliant agent discovery cards. - name: A2A description: Converse with an agent over the A2A v1.0 protocol. - name: Connectors description: Manage the connectors attached to an agent. - name: Usage description: Bucketed invocation history for an agent. - name: Contexts description: Conversational contexts and their tasks. - name: Registry description: Discoverable, pre-built connectors offered by the platform. - name: Artifacts description: Retrieve artifacts produced by tasks. - name: Feedback description: Collect human or automated feedback on tasks and messages. paths: /v2/agentic/contexts/{contextId}: parameters: - $ref: '#/components/parameters/ContextId' get: tags: - Contexts summary: Get a context description: | Returns the context's metadata together with its `tasks`, oldest first. Each task carries its full message `history`; the user's prompt for a task is the `ROLE_USER` message within that task's history (there is no separate top-level message list). operationId: ContextsGet parameters: - name: historyLength in: query description: Cap the number of history messages returned per task. schema: type: integer minimum: 0 responses: '200': description: The context and its tasks. content: application/json: schema: $ref: '#/components/schemas/ContextsDetailResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: ContextId: name: contextId in: path required: true description: Context identifier (prefixed UUIDv7). schema: $ref: '#/components/schemas/CommonContextIDValue' schemas: ContextsDetailResponse: description: | A context together with its tasks. Returned by `GET /contexts/{id}`. Tasks are ordered oldest first and each carries its full message `history` — the user's prompt for a task is the `ROLE_USER` message within that task's history. allOf: - $ref: '#/components/schemas/Contexts' - type: object required: - tasks properties: tasks: type: array description: >- The context's tasks, oldest first, each with full message history. items: $ref: '#/components/schemas/CommonTaskResponse' examples: - id: ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51 agentId: agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40 taskCount: 1 createdAt: '2026-05-19T12:00:00Z' updatedAt: '2026-05-19T12:00:01Z' expiresAt: null tasks: - id: task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62 contextId: ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51 status: state: TASK_STATE_COMPLETED timestamp: '2026-05-19T12:00:01Z' history: - role: ROLE_USER messageId: msg.0192f4c8-5a01-7c10-8a2b-1f3c5d7e9b00 parts: - text: 'Code this encounter: acute asthma exacerbation.' - role: ROLE_AGENT messageId: msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73 taskId: task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62 parts: - text: J45.901 artifacts: - artifactId: art.0192f4c8-6a9e-7f72-a35e-70c1ac6fbe84 parts: - text: J45.901 CommonContextIDValue: type: string format: context-id description: >- Context identifier. Accepts `ctx.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(ctx\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51 Contexts: type: object description: >- Lightweight context metadata, as returned in list responses. Contexts are not first-class CRUD resources: there is no explicit create or update endpoint — a context is created implicitly on the first message send (or reused by client-supplied contextId), and list is not yet implemented. required: - id properties: id: $ref: '#/components/schemas/CommonContextIDValue' agentId: $ref: '#/components/schemas/CommonAgentIDValue' taskCount: type: integer minimum: 0 readOnly: true description: Total number of tasks in the context. createdAt: type: string format: date-time description: When the context was created. updatedAt: type: string format: date-time description: When the context was last updated. expiresAt: type: - string - 'null' format: date-time description: >- When the context expires; `null` means it does not expire. Not yet implemented — the server always returns `null` and performs no TTL-based cleanup. CommonTaskResponse: type: object description: An A2A task — a unit of agent work with status, history, and artifacts. required: - id - contextId - status properties: id: $ref: '#/components/schemas/CommonTaskIDValue' contextId: $ref: '#/components/schemas/CommonContextIDValue' status: $ref: '#/components/schemas/CommonTaskStatus' examples: - state: TASK_STATE_COMPLETED timestamp: '2026-05-19T12:00:00Z' history: type: array items: $ref: '#/components/schemas/CommonMessage' description: Messages exchanged during the task, oldest first. examples: - - messageId: msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73 role: ROLE_AGENT parts: - text: J45.909 artifacts: type: array items: $ref: '#/components/schemas/CommonArtifactResponse' description: Artifacts produced by the task. examples: - - artifactId: art.0192f4c8-6a9e-7f72-a35e-70c1ac6fbe84 name: icd10-result parts: - text: J45.909 metadata: $ref: '#/components/schemas/CommonTaskMetadata' description: >- Task metadata, including `$usage` token/credit accounting. Not yet exposed through the REST binding (deferred); only the JSON-RPC binding populates this field. example: $usage: model: corti-default inputTokens: 100 outputTokens: 20 totalTokens: 120 credits: 1.2 CommonErrorResponse: type: object description: > Corti management-plane error envelope, used by all non-A2A endpoints. - **Standard** — when the error chain contains at least one `PublicError`, `code` and `message` come from the outermost `PublicError` and `details` is merged across the whole chain (outer values take precedence). - **Fallback** — when the chain contains no `PublicError`, the response is a generic `500` carrying a `requestId` for support reference. - **Validation** — a single `PublicError` whose `details.validationErrors` lists the offending fields. Field names use camelCase on the wire (e.g. `requestId`, `howToFix`). The free-form `details` object may carry arbitrary caller-defined keys. Rate limiting (HTTP 429) is not yet implemented; the server does not emit a 429 response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable, machine-readable, SCREAMING_SNAKE_CASE error code. examples: - ASSIGNMENT_CONFLICT - VALIDATION_FAILED - INTERNAL_ERROR message: type: string description: Human-readable explanation. howToFix: type: string description: Optional guidance for the caller to resolve the error. details: type: object description: | Structured context, merged from every `PublicError` in the chain (outer values win). Omitted on the generic fallback response. additionalProperties: true properties: validationErrors: type: array description: Present when `code` is `VALIDATION_FAILED`. items: type: object required: - field - reason properties: field: type: string description: The field that failed validation. reason: type: string description: Why the field failed validation. requestId: type: string description: > Correlation ID from request middleware. Included only on the generic `500` fallback so consumers can quote it in support requests. description: The error object with code, message, and optional details. examples: - error: code: ASSIGNMENT_CONFLICT message: could not complete assignment details: assignment_id: asg_99 expert_id: exp_42 - error: code: VALIDATION_FAILED message: validation failed details: validationErrors: - field: email reason: invalid format - field: name reason: required - error: code: INTERNAL_ERROR message: internal server error requestId: req_abc123 CommonAgentIDValue: type: string format: agent-id description: >- Agent identifier. Accepts `agt.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(agt\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40 CommonTaskIDValue: type: string format: task-id description: >- Task identifier. Accepts `task.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(task\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62 CommonTaskStatus: type: object description: A task's current state, with an optional status message and timestamp. required: - state properties: state: $ref: '#/components/schemas/CommonTaskState' message: $ref: '#/components/schemas/CommonMessage' timestamp: type: string format: date-time description: When the status was last updated. CommonMessage: type: object description: An A2A message — an ordered list of content parts with a role. required: - role - parts properties: messageId: $ref: '#/components/schemas/CommonMessageIDValue' contextId: $ref: '#/components/schemas/CommonContextIDValue' taskId: $ref: '#/components/schemas/CommonTaskIDValue' role: $ref: '#/components/schemas/CommonRole' parts: type: array items: $ref: '#/components/schemas/CommonPart' description: Ordered content parts of the message. referenceTaskIds: type: array description: >- Task ids this message references (A2A v1.0 `Message.referenceTaskIds`). items: $ref: '#/components/schemas/CommonTaskIDValue' extensions: type: array description: >- URIs of A2A extensions that contributed to this message (A2A v1.0 `Message.extensions`). items: type: string format: uri metadata: type: object additionalProperties: true description: > Free-form A2A metadata. Corti's own first-party keys are prefixed with `$` (à la Mixpanel) to set them apart from caller-supplied keys. A2A defines no message-level timestamp, so Corti carries one as `$timestamp` (RFC 3339 / ISO 8601) — useful for timing *user* messages, which `TaskStatus.timestamp` cannot. examples: - $timestamp: '2026-05-19T12:00:00Z' CommonArtifactResponse: type: object description: A named output produced by a task. required: - artifactId - parts properties: artifactId: $ref: '#/components/schemas/CommonArtifactIDValue' name: type: string description: Optional artifact name. examples: - icd10-result description: type: string description: A human-readable description of the artifact. extensions: type: array description: URIs of extensions that contributed to this artifact. items: type: string format: uri metadata: type: object additionalProperties: true description: Optional metadata included with the artifact. parts: type: array items: $ref: '#/components/schemas/CommonPart' description: Content parts of the artifact. examples: - - text: J45.909 CommonTaskMetadata: type: object description: > Free-form A2A task metadata. Corti's first-party keys are prefixed with `$` (à la Mixpanel) to set them apart from caller-supplied keys. Token and credit accounting is carried under `$usage`. Arbitrary additional keys are permitted. required: [] properties: $usage: $ref: '#/components/schemas/CommonUsage' additionalProperties: true CommonTaskState: type: string description: The lifecycle state of a task. enum: - TASK_STATE_SUBMITTED - TASK_STATE_WORKING - TASK_STATE_COMPLETED - TASK_STATE_FAILED - TASK_STATE_CANCELED - TASK_STATE_INPUT_REQUIRED - TASK_STATE_REJECTED - TASK_STATE_AUTH_REQUIRED CommonMessageIDValue: type: string format: message-id description: >- Message identifier. Accepts `msg.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(msg\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73 CommonRole: type: string description: The author of a message. enum: - ROLE_USER - ROLE_AGENT CommonPart: type: object description: A single content part of a message or artifact. required: [] properties: text: type: string description: The string content of the `text` part. data: type: object additionalProperties: true description: >- Arbitrary structured `data` as a JSON value (object, array, string, number, boolean, or null). filename: type: string description: An optional `filename` for the file (e.g., `document.pdf`). mediaType: type: string description: >- The `media_type` (MIME type) of the part content (e.g., `text/plain`, `application/json`, `image/png`). raw: type: string contentEncoding: base64 pattern: ^[A-Za-z0-9+/]*={0,2}$ description: The `raw` byte content of a file. Encoded as a base64 string. url: type: string description: A `url` pointing to the file's content. metadata: type: object additionalProperties: true description: Optional metadata associated with this part. additionalProperties: true CommonArtifactIDValue: type: string format: artifact-id description: >- Artifact identifier. Accepts `art.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(art\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - art.0192f4c8-6a9e-7f72-a35e-70c1ac6fbe84 CommonUsage: type: object description: > Token and credit accounting for a task, following the conventions used by major LLM providers. `inputTokens`/`outputTokens` count the prompt and completion respectively; `cachedInputTokens` is the subset of `inputTokens` served from the provider's prompt cache (a discount, not an addition), and `cacheCreationInputTokens` is the surcharge paid to *write* the cache. `totalTokens` is the all-in count. `credits` is the Corti billing unit charged for the task. required: - inputTokens - outputTokens - totalTokens properties: model: type: string description: The model identifier that served the request. examples: - corti-default inputTokens: type: integer format: int64 minimum: 0 description: Prompt tokens consumed. examples: - 100 outputTokens: type: integer format: int64 minimum: 0 description: Completion tokens produced. examples: - 20 cachedInputTokens: type: integer format: int64 minimum: 0 description: Subset of `inputTokens` served from the prompt cache (cache read). examples: - 64 cacheCreationInputTokens: type: integer format: int64 minimum: 0 description: Input tokens written to the prompt cache (cache-write surcharge). examples: - 0 totalTokens: type: integer format: int64 minimum: 0 description: Total tokens billed (`inputTokens` + `outputTokens`). examples: - 120 credits: type: number format: double minimum: 0 description: Corti billing credits charged for the task. examples: - 1.2 examples: - model: corti-default inputTokens: 100 outputTokens: 20 cachedInputTokens: 64 cacheCreationInputTokens: 0 totalTokens: 120 credits: 1.2 responses: Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' NotFound: description: The resource does not exist or is not visible to the caller. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 / OIDC bearer token. tenantHeader: type: apiKey in: header name: Tenant-Name description: The tenant the request operates within. ````