Work with contexts

This guide shows you how to manage contexts using the v2 Agentic API. Contexts are first-class resources with their own endpoints for listing, inspection, and deletion.

Prerequisites

An existing agent with at least one sent message (see Send a message)
Understanding of context and memory

List contexts

The GET /v2/agentic/contexts listing endpoint is in private preview — it returns an empty list and ignores all filters. Use GET /v2/agentic/contexts/{contextId} to retrieve a specific context.

# Replace these with your values
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Filtering

Parameter	Description
`agentId`	Restrict to contexts owned by a specific agent
`from`	Inclusive lower bound on `createdAt` (RFC 3339)
`to`	Exclusive upper bound on `createdAt` (RFC 3339)

AGENT_ID="<your-agent-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts?agentId=${AGENT_ID}&from=2026-05-19T00:00:00Z" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

The response is paginated with contexts, nextPageToken, and totalSize fields.

Get a context

CONTEXT_ID="<your-context-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Use the historyLength query parameter to cap the number of history messages returned per task:

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}?historyLength=10" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

The response includes the context’s metadata and its tasks array (oldest first). Each task carries its full message history.

{
  "id": "ctx.0192f4c8-...",
  "agentId": "agt.0192f4c8-...",
  "taskCount": 1,
  "createdAt": "2026-05-19T12:00:00Z",
  "updatedAt": "2026-05-19T12:00:01Z",
  "expiresAt": null,
  "tasks": [
    {
      "id": "task.0192f4c8-...",
      "contextId": "ctx.0192f4c8-...",
      "status": {"state": "TASK_STATE_COMPLETED", "timestamp": "2026-05-19T12:00:01Z"},
      "history": [
        {"role": "ROLE_USER", "messageId": "msg-...", "parts": [{"text": "Code this encounter."}]},
        {"role": "ROLE_AGENT", "messageId": "msg-...", "parts": [{"text": "J45.901"}]}
      ]
    }
  ]
}

Delete a context

curl -X DELETE "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Deleting a context is irreversible. All associated tasks, messages, and artifacts are permanently removed.

List tasks in a context

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Get a specific task in a context

TASK_ID="<your-task-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks/${TASK_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Get an artifact

Retrieve a specific artifact produced by a task:

ARTIFACT_ID="<your-artifact-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks/${TASK_ID}/artifacts/${ARTIFACT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

Next steps

Learn how to export traces for observability
Read about context and memory concepts
Learn how to submit feedback on task results

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Prerequisites

List contexts

Filtering

Get a context

Delete a context

List tasks in a context

Get a specific task in a context

Get an artifact

Next steps

​Prerequisites

​List contexts

​Filtering

​Get a context

​Delete a context

​List tasks in a context

​Get a specific task in a context

​Get an artifact

​Next steps

Prerequisites

List contexts

Filtering

Get a context

Delete a context

List tasks in a context

Get a specific task in a context

Get an artifact

Next steps