Create a context

Created empty, and not queryable until you import sources and curate them — curate is explicit. Optionally seed a manifest. A work context is the exception: queryable from day zero, built from traces of work rather than documents.

POST /contexts

Create a context

cURL

curl --request POST \
  --url https://{host}/api/contexts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slug": "<string>",
  "name": "<string>",
  "description": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": {
        "enabled": true,
        "embedding_model": "multilingual-e5-large",
        "chunking": {
          "strategy": "markdown_heading",
          "target_size": 512,
          "overlap": 64,
          "respect_sections": true
        },
        "keyword": {
          "enabled": true
        }
      },
      "artifacts": {
        "enabled": false,
        "artifact_model": "lite",
        "artifact_types": [
          {
            "name": "<string>",
            "kind": "topic",
            "scope": "corpus",
            "icon": "<string>",
            "description": "<string>",
            "coverage": [
              "<string>"
            ],
            "sections": [
              "<string>"
            ],
            "min_doc_count": 1,
            "format": "markdown",
            "columns": [
              {
                "name": "<string>",
                "type": "TEXT",
                "description": "<string>"
              }
            ],
            "natural_key": [
              "<string>"
            ]
          }
        ],
        "edge_types": [
          {
            "name": "<string>",
            "from": "<string>",
            "to": "<string>",
            "description": "<string>",
            "attributes": [
              "<string>"
            ]
          }
        ],
        "min_doc_count": 1,
        "max_tokens": 1500,
        "max_doc_chars": 60000,
        "extraction_window_chars": 0,
        "mention_max_chars": 400,
        "max_mentions_per_artifact": 40,
        "mention_context_chars": 8000,
        "max_artifacts_per_type": 10000
      }
    },
    "optimize": {
      "schedule": "0 * * * *",
      "latency_threshold_ms": 60000,
      "min_group_size": 2,
      "eval_pass_rate_threshold": 1,
      "max_iterations": 20
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "kind": "search",
  "pinecone_api_key": "<string>"
}
'

200

{
  "id": "<string>",
  "slug": "<string>",
  "name": "<string>",
  "kind": "search",
  "created_by": "<string>",
  "description": "<string>",
  "is_optimizing": true,
  "has_sources": true,
  "is_curating": true,
  "is_importing": true,
  "is_exploring": true,
  "is_restoring": true,
  "is_grooming": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": {
        "enabled": true,
        "embedding_model": "multilingual-e5-large",
        "chunking": {
          "strategy": "markdown_heading",
          "target_size": 512,
          "overlap": 64,
          "respect_sections": true
        },
        "keyword": {
          "enabled": true
        }
      },
      "artifacts": {
        "enabled": false,
        "artifact_model": "lite",
        "artifact_types": [
          {
            "name": "<string>",
            "kind": "topic",
            "scope": "corpus",
            "icon": "<string>",
            "description": "<string>",
            "coverage": [
              "<string>"
            ],
            "sections": [
              "<string>"
            ],
            "min_doc_count": 1,
            "format": "markdown",
            "columns": [
              {
                "name": "<string>",
                "type": "TEXT",
                "description": "<string>"
              }
            ],
            "natural_key": [
              "<string>"
            ]
          }
        ],
        "edge_types": [
          {
            "name": "<string>",
            "from": "<string>",
            "to": "<string>",
            "description": "<string>",
            "attributes": [
              "<string>"
            ]
          }
        ],
        "min_doc_count": 1,
        "max_tokens": 1500,
        "max_doc_chars": 60000,
        "extraction_window_chars": 0,
        "mention_max_chars": 400,
        "max_mentions_per_artifact": 40,
        "mention_context_chars": 8000,
        "max_artifacts_per_type": 10000
      }
    },
    "optimize": {
      "schedule": "0 * * * *",
      "latency_threshold_ms": 60000,
      "min_group_size": 2,
      "eval_pass_rate_threshold": 1,
      "max_iterations": 20
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "semantic_index": "<string>",
  "keyword_index": "<string>",
  "optimize_task_id": "<string>",
  "optimize_score": 123,
  "optimize_iterations": 123,
  "last_optimized_at": "2023-11-07T05:31:56Z",
  "last_curated_at": "2023-11-07T05:31:56Z",
  "last_source_import_at": "2023-11-07T05:31:56Z",
  "curate_task_id": "<string>",
  "import_task_id": "<string>",
  "explore_task_id": "<string>",
  "restore_task_id": "<string>",
  "manifest_suggestion": {
    "matches": [
      {
        "template_id": "<string>",
        "rationale": "<string>",
        "confidence": 123
      }
    ],
    "none": true,
    "explored_at": "2023-11-07T05:31:56Z",
    "task_id": "<string>"
  },
  "sample_queries": [
    "<string>"
  ],
  "groom_task_id": "<string>",
  "groom_artifact_count": 123,
  "last_groomed_at": "2023-11-07T05:31:56Z",
  "stats": {
    "tasks_total": 123,
    "tasks_active": 123,
    "tasks_completed": 123,
    "tasks_failed": 123,
    "tasks_cancelled": 123,
    "tokens_total": 123,
    "runtime_seconds": 123
  }
}

Authorizations

bearerAuthapiKey

Authorization · string · header · required

Session token from POST /auth/login, sent as Authorization: Bearer <token>.

Headers

X-Pinecone-Api-Version · string · default: 2026-07

Date-based contract version, echoed back on the same header. Omit for the default (2026-07); send unstable for the in-development surface. An unrecognized value is rejected with 400 unsupported_api_version.

Body

application/json

What a new context is created with. Only slug and name are required.

slug · string · required

3–64 chars, lowercase alnum + hyphens, starts with a letter

name · string · required

1–128 chars

description · string

Free-text summary of what the context will hold.

guide · string

High-level standing instructions for the query runtime.

manifest · object

Seed manifest (validated against the manifest schema)

Show child attributes

kind · string · default: search

How the context is built. search — built from source documents, and must be curated before it can be queried. work — built from traces of work done, queryable immediately, consolidated by groom rather than curate.

pinecone_api_key · string

Pinecone API key used to provision the context's managed index. Omit it under BYOC, where the deployment holds its own credential.

Response

200

application/json

The created context

What context endpoints return — the stored context plus the lifecycle flags derived from its in-flight tasks.

id · string · required

Stable UUID. Accepted anywhere {slug} is.

slug · string · required

URL-safe name, unique within the project. Mutable via PUT.

name · string · required

Human-readable display name.

kind · string · default: search · required

How the context is built. search — built from source documents, and must be curated before it can be queried. work — built from traces of work done, queryable immediately, consolidated by groom rather than curate.

created_by · string · required

Principal that created the context.

description · string | null · required

Free-text summary of what the context holds.

is_optimizing · boolean · required

An optimize task is in flight.

has_sources · boolean · required

The source tree holds at least one file. False blocks curate.

is_curating · boolean · required

A curate task is in flight.

is_importing · boolean · required

An import task is in flight.

is_exploring · boolean · required

An explore task is in flight.

is_restoring · boolean · required

A restore task is in flight.

is_grooming · boolean · required

A groom task is in flight. Work contexts only.

created_at · string<date-time> · required

When the context was created.

updated_at · string<date-time> · required

When the context last changed.

workspace · string

Owning workspace. Absent off a workspace-enabled cluster.

guide · string

High-level standing instructions the query runtime reads on every turn.

manifest · object

Pinned manifest document. Absent when the context runs on validator defaults.

Show child attributes

semantic_index · string | null

Host of the index backing this context's vector retrieval. Null until a curate resolves one.

keyword_index · string | null

Host of the index backing keyword retrieval. The same host as semantic_index today — the two names are separate seams over one index.

optimize_task_id · string | null

The optimize task — the running one, or the last to finish.

optimize_score · number<double> | null

Eval pass rate the last optimize's best iteration scored.

optimize_iterations · integer | null

How many candidate manifests the last run tried.

last_optimized_at · string<date-time> | null

When an optimize last persisted a tuned manifest.

last_curated_at · string<date-time> | null

When a curate last flipped a new index version live.

last_source_import_at · string<date-time> | null

When sources were last staged by an upload or import.

curate_task_id · string | null

The curate task — the running one, or the last to finish.

import_task_id · string | null

The import task — the running one, or the last to finish.

explore_task_id · string | null

The explore task — the running one, or the last to finish.

restore_task_id · string | null

The restore task — the running one, or the last to finish.

manifest_suggestion · object

Outcome of the last explore run, pinned to the context row. A proposal only — apply it by writing the manifest and forcing a curate.

Show child attributes

sample_queries · string[]

Example questions the curated corpus can answer, written by the last curate.

One example question.

groom_task_id · string

The groom task — the running one, or the last to finish.

groom_artifact_count · integer<int64>

Artifacts the last groom left in the work context.

last_groomed_at · string<date-time>

When a groom last consolidated the work context.

stats · object

Aggregate task counters. Populated only on the list endpoint.

Show child attributes