Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

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

cURL
curl --request POST \
  --url https://{host}/api/contexts \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "slug": "<string>",
  "name": "<string>",
  "description": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": null,
      "artifacts": null
    },
    "optimize": {
      "schedule": "<string>",
      "latency_threshold_ms": 123,
      "min_group_size": 123,
      "eval_pass_rate_threshold": 123,
      "max_iterations": 123
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "kind": "<string>",
  "pinecone_api_key": "<string>"
}'
Python
import requests

url = "https://{host}/api/contexts"

payload = {
  "slug": "<string>",
  "name": "<string>",
  "description": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": None,
      "artifacts": None
    },
    "optimize": {
      "schedule": "<string>",
      "latency_threshold_ms": 123,
      "min_group_size": 123,
      "eval_pass_rate_threshold": 123,
      "max_iterations": 123
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "kind": "<string>",
  "pinecone_api_key": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
JavaScript
const options = {method: "POST", headers: {"Authorization": "Bearer <token>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>", "Content-Type": "application/json"}, body: JSON.stringify({
  "slug": "<string>",
  "name": "<string>",
  "description": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": null,
      "artifacts": null
    },
    "optimize": {
      "schedule": "<string>",
      "latency_threshold_ms": 123,
      "min_group_size": 123,
      "eval_pass_rate_threshold": 123,
      "max_iterations": 123
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "kind": "<string>",
  "pinecone_api_key": "<string>"
})};

fetch("https://{host}/api/contexts", options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/contexts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"slug\":\"<string>\",\"name\":\"<string>\",\"description\":\"<string>\",\"guide\":\"<string>\",\"manifest\":{\"curate\":{\"chunks\":null,\"artifacts\":null},\"optimize\":{\"schedule\":\"<string>\",\"latency_threshold_ms\":123,\"min_group_size\":123,\"eval_pass_rate_threshold\":123,\"max_iterations\":123},\"search\":{\"instructions\":\"<string>\"}},\"kind\":\"<string>\",\"pinecone_api_key\":\"<string>\"}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/contexts"

	payload := strings.NewReader("{\"slug\":\"<string>\",\"name\":\"<string>\",\"description\":\"<string>\",\"guide\":\"<string>\",\"manifest\":{\"curate\":{\"chunks\":null,\"artifacts\":null},\"optimize\":{\"schedule\":\"<string>\",\"latency_threshold_ms\":123,\"min_group_size\":123,\"eval_pass_rate_threshold\":123,\"max_iterations\":123},\"search\":{\"instructions\":\"<string>\"}},\"kind\":\"<string>\",\"pinecone_api_key\":\"<string>\"}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
Java
HttpResponse<String> response = Unirest.post("https://{host}/api/contexts")
  .header("Authorization", "Bearer <token>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .header("Content-Type", "application/json")
  .body("{\"slug\":\"<string>\",\"name\":\"<string>\",\"description\":\"<string>\",\"guide\":\"<string>\",\"manifest\":{\"curate\":{\"chunks\":null,\"artifacts\":null},\"optimize\":{\"schedule\":\"<string>\",\"latency_threshold_ms\":123,\"min_group_size\":123,\"eval_pass_rate_threshold\":123,\"max_iterations\":123},\"search\":{\"instructions\":\"<string>\"}},\"kind\":\"<string>\",\"pinecone_api_key\":\"<string>\"}")
  .asString();
Ruby
require 'uri'
require 'net/http'

url = URI("https://{host}/api/contexts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\"slug\":\"<string>\",\"name\":\"<string>\",\"description\":\"<string>\",\"guide\":\"<string>\",\"manifest\":{\"curate\":{\"chunks\":null,\"artifacts\":null},\"optimize\":{\"schedule\":\"<string>\",\"latency_threshold_ms\":123,\"min_group_size\":123,\"eval_pass_rate_threshold\":123,\"max_iterations\":123},\"search\":{\"instructions\":\"<string>\"}},\"kind\":\"<string>\",\"pinecone_api_key\":\"<string>\"}"

response = http.request(request)
puts response.read_body
200
{
  "id": "<string>",
  "slug": "<string>",
  "name": "<string>",
  "kind": "<string>",
  "workspace": "<string>",
  "created_by": "<string>",
  "description": "<string>",
  "guide": "<string>",
  "manifest": {
    "curate": {
      "chunks": null,
      "artifacts": null
    },
    "optimize": {
      "schedule": "<string>",
      "latency_threshold_ms": 123,
      "min_group_size": 123,
      "eval_pass_rate_threshold": 123,
      "max_iterations": 123
    },
    "search": {
      "instructions": "<string>"
    }
  },
  "semantic_index": "<string>",
  "keyword_index": "<string>",
  "is_optimizing": true,
  "optimize_task_id": "<string>",
  "optimize_score": 123,
  "optimize_iterations": 123,
  "last_optimized_at": "<string>",
  "last_curated_at": "<string>",
  "has_sources": true,
  "last_source_import_at": "<string>",
  "is_curating": true,
  "curate_task_id": "<string>",
  "is_importing": true,
  "import_task_id": "<string>",
  "is_exploring": true
}
400
{
  "message": "<string>",
  "code": "<string>"
}
403
{
  "message": "<string>",
  "code": "<string>"
}

Authorizations

Section titled “Authorizations”
Authorizationstringrequired

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

Headers

Section titled “Headers”
X-Pinecone-Api-Version?string

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.

Typestring
Default2026-07

Body

Section titled “Body”
slugstringrequired

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

Typestring
namestringrequired

1–128 chars

Typestring
description?string

Free-text summary of what the context will hold.

Typestring
guide?string

High-level standing instructions for the query runtime.

Typestring
manifest?object

Seed manifest (validated against the manifest schema)

Typeobject
Show child attributes
curate?object

What curate builds out of the sources — the chunk leg, the artifact leg, or both.

Typeobject
Show child attributes
chunks?object

The chunk leg — sources split into passages, embedded for semantic search and optionally indexed for keyword search.

Typeobject
Show child attributes
enabled?boolean

Whether curate builds the chunk leg at all.

Typeboolean
Defaulttrue
embedding_model?string

Model that embeds the chunks.

Required string length: 0 - 128

Typestring
Defaultmultilingual-e5-large
chunking?object

How a source is cut into chunks.

Typeobject
keyword?object

The lexical index built alongside the vectors, for exact-term matching.

Typeobject
artifacts?object

The artifact leg: knowledge an LLM distills out of the sources, as prose files or database rows. Off by default.

Typeobject
Show child attributes
enabled?boolean

Whether curate extracts artifacts at all.

Typeboolean
Defaultfalse
artifact_model?string

Model tier that does the extraction. standard reads more carefully at a higher token cost.

Typestring
Defaultlite
artifact_types?object[]

What kinds of artifact to extract. Nothing is extracted until at least one is declared.

Typeobject[]
edge_types?object[]

Typed, directed relationships between artifact types, which turn the artifacts into a graph the agent can traverse.

Typeobject[]
min_doc_count?integer

How many source documents must mention a corpus-scoped subject before it earns an artifact. Raise it to suppress one-off mentions. An artifact type may override it.

Required range: 1 <= x <= 64

Typeinteger
Default1
max_tokens?integer

Output cap for one extracted artifact, in tokens.

Required range: 128 <= x <= 8192

Typeinteger
Default1500
max_doc_chars?integer

Input cap for one extraction call, in characters. With windowing off this also caps how much of a source is read at all; everything beyond it is dropped.

Required range: 1000 <= x <= 2000000

Typeinteger
Default60000
extraction_window_chars?integer

Window size for walking a long source across several extraction calls, so its back half is covered rather than dropped. 0 opts out and reads only the head, up to max_doc_chars.

Required range: 0 <= x <= 1000000

Typeinteger
Default0
mention_max_chars?integer

Cap on one recorded mention — what a single document says about the subject — in characters.

Required range: 100 <= x <= 4000

Typeinteger
Default400
max_mentions_per_artifact?integer

How many mentions are fed into the pass that reduces them into one corpus-wide artifact.

Required range: 1 <= x <= 500

Typeinteger
Default40
mention_context_chars?integer

Cap on those mentions once concatenated, in characters. Applied after max_mentions_per_artifact.

Required range: 1000 <= x <= 100000

Typeinteger
Default8000
max_artifacts_per_type?integer

How many artifacts one type may produce. Omit for no cap.

Required range: 1 <= x <= 10000

Typeinteger
Default10000
optimize?object

The scheduled self-tuning loop: it clusters the queries that answered badly and tries candidate manifests against an ephemeral index until one reproduces the recorded answers.

Typeobject
Show child attributes
schedule?string

Cron expression the tuning loop runs on.

Required string length: 0 - 128

Typestring
Default0 * * * *
latency_threshold_ms?integer

A query slower than this counts as a problem worth tuning for, as does any query that fell back from artifacts to chunks. 0 disables the latency test, leaving only fallback.

Required range: 0 <= x <= 600000

Typeinteger
Default60000
min_group_size?integer

How many near-duplicate problem queries must cluster together before the loop tunes for them. Keeps a one-off slow query from triggering a manifest change.

Required range: 1 <= x <= 100

Typeinteger
Default2
eval_pass_rate_threshold?number

Fraction of eval queries a candidate manifest must answer correctly to be considered ready. 1 demands all of them.

Required range: 0 <= x <= 1

Typenumber
Default1
max_iterations?integer

How many candidate manifests the loop tries before stopping with its best.

Required range: 1 <= x <= 100

Typeinteger
Default20
search?object

Standing instructions for the query runtime, pinned on the context rather than sent per turn.

Typeobject
Show child attributes
instructions?string

The context's default system prompt, applied to every turn in scope. A session's own system_prompt appends to it rather than replacing it.

Typestring
kind?string

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.

Typestring
Defaultsearch
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.

Typestring

Response

Section titled “Response”

200 — The created context

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

idstringrequired

Stable UUID. Accepted anywhere slug is.

Typestring
slugstringrequired

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

Typestring
namestringrequired

Human-readable display name.

Typestring
kindstringrequired

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.

Typestring
Defaultsearch
workspace?string

Owning workspace. Absent off a workspace-enabled cluster.

Typestring
created_bystringrequired

Principal that created the context.

Typestring
descriptionstring | nullrequired

Free-text summary of what the context holds.

Typestring | null
guide?string

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

Typestring
manifest?object

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

Typeobject
Show child attributes
curate?object

What curate builds out of the sources — the chunk leg, the artifact leg, or both.

Typeobject
Show child attributes
chunks?object

The chunk leg — sources split into passages, embedded for semantic search and optionally indexed for keyword search.

Typeobject
Show child attributes
enabled?boolean

Whether curate builds the chunk leg at all.

Typeboolean
Defaulttrue
embedding_model?string

Model that embeds the chunks.

Required string length: 0 - 128

Typestring
Defaultmultilingual-e5-large
chunking?object

How a source is cut into chunks.

Typeobject
keyword?object

The lexical index built alongside the vectors, for exact-term matching.

Typeobject
artifacts?object

The artifact leg: knowledge an LLM distills out of the sources, as prose files or database rows. Off by default.

Typeobject
Show child attributes
enabled?boolean

Whether curate extracts artifacts at all.

Typeboolean
Defaultfalse
artifact_model?string

Model tier that does the extraction. standard reads more carefully at a higher token cost.

Typestring
Defaultlite
artifact_types?object[]

What kinds of artifact to extract. Nothing is extracted until at least one is declared.

Typeobject[]
edge_types?object[]

Typed, directed relationships between artifact types, which turn the artifacts into a graph the agent can traverse.

Typeobject[]
min_doc_count?integer

How many source documents must mention a corpus-scoped subject before it earns an artifact. Raise it to suppress one-off mentions. An artifact type may override it.

Required range: 1 <= x <= 64

Typeinteger
Default1
max_tokens?integer

Output cap for one extracted artifact, in tokens.

Required range: 128 <= x <= 8192

Typeinteger
Default1500
max_doc_chars?integer

Input cap for one extraction call, in characters. With windowing off this also caps how much of a source is read at all; everything beyond it is dropped.

Required range: 1000 <= x <= 2000000

Typeinteger
Default60000
extraction_window_chars?integer

Window size for walking a long source across several extraction calls, so its back half is covered rather than dropped. 0 opts out and reads only the head, up to max_doc_chars.

Required range: 0 <= x <= 1000000

Typeinteger
Default0
mention_max_chars?integer

Cap on one recorded mention — what a single document says about the subject — in characters.

Required range: 100 <= x <= 4000

Typeinteger
Default400
max_mentions_per_artifact?integer

How many mentions are fed into the pass that reduces them into one corpus-wide artifact.

Required range: 1 <= x <= 500

Typeinteger
Default40
mention_context_chars?integer

Cap on those mentions once concatenated, in characters. Applied after max_mentions_per_artifact.

Required range: 1000 <= x <= 100000

Typeinteger
Default8000
max_artifacts_per_type?integer

How many artifacts one type may produce. Omit for no cap.

Required range: 1 <= x <= 10000

Typeinteger
Default10000
optimize?object

The scheduled self-tuning loop: it clusters the queries that answered badly and tries candidate manifests against an ephemeral index until one reproduces the recorded answers.

Typeobject
Show child attributes
schedule?string

Cron expression the tuning loop runs on.

Required string length: 0 - 128

Typestring
Default0 * * * *
latency_threshold_ms?integer

A query slower than this counts as a problem worth tuning for, as does any query that fell back from artifacts to chunks. 0 disables the latency test, leaving only fallback.

Required range: 0 <= x <= 600000

Typeinteger
Default60000
min_group_size?integer

How many near-duplicate problem queries must cluster together before the loop tunes for them. Keeps a one-off slow query from triggering a manifest change.

Required range: 1 <= x <= 100

Typeinteger
Default2
eval_pass_rate_threshold?number

Fraction of eval queries a candidate manifest must answer correctly to be considered ready. 1 demands all of them.

Required range: 0 <= x <= 1

Typenumber
Default1
max_iterations?integer

How many candidate manifests the loop tries before stopping with its best.

Required range: 1 <= x <= 100

Typeinteger
Default20
search?object

Standing instructions for the query runtime, pinned on the context rather than sent per turn.

Typeobject
Show child attributes
instructions?string

The context's default system prompt, applied to every turn in scope. A session's own system_prompt appends to it rather than replacing it.

Typestring
semantic_index?string | null

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

Typestring | null
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.

Typestring | null
is_optimizingbooleanrequired

An optimize task is in flight.

Typeboolean
optimize_task_id?string | null

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

Typestring | null
optimize_score?number | null

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

Typenumber | null
optimize_iterations?integer | null

How many candidate manifests the last run tried.

Typeinteger | null
last_optimized_at?string | null

When an optimize last persisted a tuned manifest.

Typestring | null
last_curated_at?string | null

When a curate last flipped a new index version live.

Typestring | null
has_sourcesbooleanrequired

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

Typeboolean
last_source_import_at?string | null

When sources were last staged by an upload or import.

Typestring | null
is_curatingbooleanrequired

A curate task is in flight.

Typeboolean
curate_task_id?string | null

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

Typestring | null
is_importingbooleanrequired

An import task is in flight.

Typeboolean
import_task_id?string | null

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

Typestring | null
is_exploringbooleanrequired

An explore task is in flight.

Typeboolean
explore_task_id?string | null

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

Typestring | null
is_restoringbooleanrequired

A restore task is in flight.

Typeboolean
restore_task_id?string | null

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

Typestring | null
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.

Typeobject
Show child attributes
matchesobject[]required

Proposed templates, best fit first.

Typeobject[]
Show child attributes
template_idstringrequired

Catalog entry the run proposes for this corpus.

Typestring
rationalestringrequired

Why the run thinks this template fits the corpus.

Typestring
confidencenumberrequired

How sure the run is, 0–1. Low-confidence proposals are dropped before this point.

Typenumber
nonebooleanrequired

True when no template fit

Typeboolean
explored_atstringrequired

When the run produced this proposal.

Typestring
task_id?string

The explore task that produced it.

Typestring
sample_queries?string[]

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

Typestring[]
is_groomingbooleanrequired

A groom task is in flight. Work contexts only.

Typeboolean
groom_task_id?string

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

Typestring
groom_artifact_count?integer

Artifacts the last groom left in the work context.

Typeinteger
last_groomed_at?string

When a groom last consolidated the work context.

Typestring
created_atstringrequired

When the context was created.

Typestring
updated_atstringrequired

When the context last changed.

Typestring
stats?object

Aggregate task counters. Populated only on the list endpoint.

Typeobject
Show child attributes
tasks_totalintegerrequired

Tasks this context has ever run.

Typeinteger
tasks_activeintegerrequired

Tasks in a non-terminal state.

Typeinteger
tasks_completedintegerrequired

Tasks that finished successfully.

Typeinteger
tasks_failedintegerrequired

Tasks that ended in failure.

Typeinteger
tasks_cancelledintegerrequired

Runs stopped before they finished.

Typeinteger
tokens_totalintegerrequired

Prompt plus completion tokens across every task.

Typeinteger
runtime_secondsintegerrequired

Summed container runtime across every task.

Typeinteger
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu