Work with contexts

Learn how to list, inspect, and delete contexts, and how to retrieve tasks within a context.

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