> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve context from an assistant
> Retrieve context snippets from an assistant to use as part of RAG or any agentic flow.
For guidance and examples, see [Retrieve context snippets](https://docs.pinecone.io/guides/assistant/retrieve-context-snippets).
```bash curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/context" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-04" \
-d '{
"query": "Who is the CFO of Netflix?"
}'
```
```json curl theme={null}
{
"snippets":
[
{
"type":"text",
"content":"EXHIBIT 31.3\nCERTIFICATION OF CHIEF FINANCIAL OFFICER\nPURSUANT TO SECTION 302 OF THE SARBANES-OXLEY ACT OF 2002\nI, Spencer Neumann, certify that: ...",
"score":0.9960699,
"reference":
{
"type":"pdf",
"file":
{
"status":"Available","id":"e6034e51-0bb9-4926-84c6-70597dbd07a7",
"name":"Netflix-10-K-01262024.pdf",
"size":1073470,
"metadata":null,
"updated_on":"2024-11-21T22:59:10.426001030Z",
"created_on":"2024-11-21T22:58:35.879120257Z",
"signed_url":"https://storage.googleapis.com..."
},
"pages":[78]
}
},
{
"type":"text",
"content":"EXHIBIT 32.1\n..."
...
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /chat/{assistant_name}/context
openapi: 3.0.3
info:
title: Pinecone assistant data plane API
description: >-
Pinecone Assistant Engine is a context engine to store and retrieve relevant
knowledge from millions of documents at scale. This API supports
interactions with assistants.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-04
servers:
- url: https://{assistant_host}
variables:
assistant_host:
default: unknown
description: The host of the created assistant
security:
- ApiKeyAuth: []
tags:
- name: Manage Assistants
description: Actions that manage Assistants
paths:
/chat/{assistant_name}/context:
post:
tags:
- Manage Assistants
summary: Retrieve context from an assistant
description: >-
Retrieve context snippets from an assistant to use as part of RAG or any
agentic flow.
For guidance and examples, see [Retrieve context
snippets](https://docs.pinecone.io/guides/assistant/retrieve-context-snippets).
operationId: context_assistant
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-04
type: string
style: simple
- in: path
name: assistant_name
description: The name of the assistant to be described.
required: true
schema:
type: string
example: test-assistant
style: simple
requestBody:
description: The desired configuration to retrieve context from an assistant.
content:
application/json:
schema:
$ref: '#/components/schemas/ContextRequest'
required: true
responses:
'200':
description: Context retrieval process successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ContextModel'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
files-validation-error:
summary: Validation error on ingest.
value:
error:
code: INVALID_ARGUMENT
message: >-
Uploaded file can only currently be either a pdf or txt
file
status: 400
'401':
description: 'Unauthorized. Possible causes: Invalid API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
error:
code: UNAUTHENTICATED
message: Invalid API key.
status: 401
'404':
description: Assistant not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
assistant-not-found:
summary: Assistant not found.
value:
error:
code: NOT_FOUND
message: Assistant "example-assistant" not found.
status: 404
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
error:
code: UNKNOWN
message: Internal server error
status: 500
components:
schemas:
ContextRequest:
description: Parameters to retrieve context from an assistant.
type: object
properties:
query:
description: >-
The query that is used to generate the context. Exactly one of query
or messages should be provided.
type: string
filter:
example:
genre:
$ne: documentary
description: >-
Optionally filter which documents can be retrieved using the
following metadata fields.
type: object
messages:
description: >-
The list of messages to use for generating the context. Exactly one
of query or messages should be provided.
type: array
items:
$ref: '#/components/schemas/MessageModel'
top_k:
example: 20
description: >-
The maximum number of context snippets to return. Default is 16.
Maximum is 64.
type: integer
snippet_size:
example: 4096
description: >-
The maximum context snippet size. Default is 2048 tokens. Minimum is
512 tokens. Maximum is 8192 tokens.
type: integer
multimodal:
description: >-
Whether or not to retrieve image-related context snippets. If
`false`, only text snippets are returned.
default: true
type: boolean
include_binary_content:
description: >-
If image-related context snippets are returned, this field
determines whether or not they should include base64 image data. If
`false`, only the image captions are returned. Only available when
`multimodal=true`.
default: true
type: boolean
ContextModel:
description: Describes the context returned by an assistant in response to a query.
type: object
properties:
id:
description: A unique identifier for this context response.
type: string
snippets:
description: A list of context snippets relevant to the user's query.
type: array
items:
$ref: '#/components/schemas/SnippetModel'
usage:
$ref: '#/components/schemas/UsageModel'
required:
- snippets
- usage
ErrorResponse:
example:
error:
code: TOO_MANY_REQUESTS
message: Too many get or list assistant requests, try again later
status: 429
description: The response shape used for all error responses.
type: object
properties:
status:
example: 500
description: The HTTP status code of the error.
type: integer
error:
example:
code: INVALID_ARGUMENT
message: 'Invalid region: Valid options are us, eu'
description: Detailed information about the error that occurred.
type: object
properties:
code:
description: The status code associated with the error.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- QUOTA_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- UNIMPLEMENTED
- INTERNAL
- UNAVAILABLE
- DATA_LOSS
- FORBIDDEN
- TOO_MANY_REQUESTS
type: string
message:
example: Message content cannot be empty
description: A message providing details about the error.
type: string
details:
description: >-
Additional information about the error. This field is not
guaranteed to be present.
type: object
required:
- code
- message
required:
- status
- error
MessageModel:
description: Describes the format of a message in a chat.
type: object
properties:
role:
description: >-
The role of the message author, it can be `user`, `assistant`, or
`system`.
type: string
content:
description: The textual content of this partial message.
type: string
SnippetModel:
description: Represents a part of a document that is relevant to the user query.
discriminator:
propertyName: type
mapping:
text:
$ref: '#/components/schemas/TextSnippetModel'
multimodal:
$ref: '#/components/schemas/MultiModalSnippetModel'
type: object
oneOf:
- $ref: '#/components/schemas/TextSnippetModel'
- $ref: '#/components/schemas/MultiModalSnippetModel'
UsageModel:
description: >-
Describes the token usage associated with interactions with an
assistant.
type: object
properties:
prompt_tokens:
description: >-
For chat interactions, the number of tokens in the LLM request
(message, context snippets, and system prompt).
For context retrieval, the number of tokens in the LLM request used
to generate search queries from the messages, plus the tokens in the
retrieved context snippets.
type: integer
completion_tokens:
description: >-
For chat interactions, the number of tokens in the assistant's
response.
For context retrieval, this is always 0.
type: integer
total_tokens:
description: >-
The total number of tokens used, equal to the sum of `prompt_tokens`
and `completion_tokens`.
type: integer
TextSnippetModel:
title: Text context snippet
description: Represents a text context snippet.
type: object
properties:
type:
description: The type of context snippet. Always `text`.
type: string
content:
description: The textual content of the snippet.
type: string
score:
description: >-
A numerical score indicating the relevance of this snippet to the
query.
type: number
format: float
reference:
$ref: '#/components/schemas/TypedReferenceModel'
required:
- type
- content
- score
- reference
MultiModalSnippetModel:
title: Multimodal context snippet
description: Represents a multimodal context snippet.
type: object
properties:
type:
description: The type of context snippet. Always `multimodal`.
type: string
content:
description: >-
A list of multimodal content blocks (text, images, etc.) included in
this snippet.
type: array
items:
$ref: '#/components/schemas/MultiModalContentBlocksModel'
score:
description: >-
A numerical score indicating the relevance of this snippet to the
user's query.
type: number
format: float
reference:
$ref: '#/components/schemas/TypedReferenceModel'
required:
- type
- content
- score
- reference
TypedReferenceModel:
description: Represents a reference for the information provided.
discriminator:
propertyName: type
mapping:
text:
$ref: '#/components/schemas/TextReferenceModel'
json:
$ref: '#/components/schemas/JsonReferenceModel'
markdown:
$ref: '#/components/schemas/MarkdownReferenceModel'
pdf:
$ref: '#/components/schemas/PdfReferenceModel'
doc_x:
$ref: '#/components/schemas/DocxReferenceModel'
type: object
oneOf:
- $ref: '#/components/schemas/TextReferenceModel'
- $ref: '#/components/schemas/JsonReferenceModel'
- $ref: '#/components/schemas/MarkdownReferenceModel'
- $ref: '#/components/schemas/PdfReferenceModel'
- $ref: '#/components/schemas/DocxReferenceModel'
MultiModalContentBlocksModel:
description: Represents a block in the multimodal content of a context snippet.
discriminator:
propertyName: type
mapping:
text:
$ref: '#/components/schemas/MultiModalContentTextBlockModel'
image:
$ref: '#/components/schemas/MultiModalContentImageBlockModel'
type: object
oneOf:
- $ref: '#/components/schemas/MultiModalContentTextBlockModel'
- $ref: '#/components/schemas/MultiModalContentImageBlockModel'
TextReferenceModel:
title: Text document reference
description: Represents a reference to a part of a text document.
type: object
properties:
type:
description: The type of reference. Always `text`.
type: string
file:
$ref: '#/components/schemas/AssistantFileModel'
required:
- type
- file
JsonReferenceModel:
title: JSON document reference
description: Represents a reference to a JSON document.
type: object
properties:
type:
description: The type of reference. Always `json`.
type: string
file:
$ref: '#/components/schemas/AssistantFileModel'
required:
- type
- file
MarkdownReferenceModel:
title: Markdown document reference
description: Represents a reference to a part of a markdown document.
type: object
properties:
type:
description: The type of reference. Always `markdown`.
type: string
file:
$ref: '#/components/schemas/AssistantFileModel'
required:
- type
- file
PdfReferenceModel:
title: PDF document reference
description: Represents a reference to a part of a PDF document.
type: object
properties:
type:
description: The type of reference. Always `pdf`.
type: string
file:
$ref: '#/components/schemas/AssistantFileModel'
pages:
description: >-
A list of page numbers in the PDF document that are relevant to the
query.
type: array
items:
type: integer
required:
- type
- file
- pages
DocxReferenceModel:
title: DOCX document reference
description: Represents a reference to a part of a DOCX document.
type: object
properties:
type:
description: The type of reference. Always `doc_x`.
type: string
file:
$ref: '#/components/schemas/AssistantFileModel'
pages:
description: >-
A list of page numbers in the DOCX document that are relevant to the
query.
type: array
items:
type: integer
required:
- type
- file
- pages
MultiModalContentTextBlockModel:
title: Multimodal text content block
description: Represents a text block in a multimodal context snippet.
type: object
properties:
type:
description: The type of multimodal content block. Always `text`.
type: string
text:
description: The text content of this multimodal block.
type: string
required:
- type
- text
MultiModalContentImageBlockModel:
title: Multimodal image content block
description: Represents an image block in a multimodal context snippet.
type: object
properties:
type:
description: The type of multimodal content block. Always `image`.
type: string
caption:
description: A caption describing the image.
type: string
image:
$ref: '#/components/schemas/ImageModel'
required:
- type
- caption
AssistantFileModel:
description: The response format for a successful file upload request.
type: object
properties:
name:
description: The name of the uploaded file.
type: string
id:
description: >-
The unique identifier for the uploaded file. This may be a
user-provided identifier or a system-generated ID.
type: string
size:
example: 1048576
description: The size of the uploaded file, in bytes.
type: integer
format: int64
metadata:
nullable: true
example:
created_by: Jane Doe
published: '2025-10-01T00:00:00.000Z'
tags:
- report
- Q4
- analytics
description: >-
Optional metadata associated with the file. This metadata can be
used to filter files when listing them or to restrict search results
when querying the assistant.
type: object
created_on:
example: '2025-10-01T12:30:00.000Z'
description: >-
The timestamp when the file was uploaded, in ISO 8601 format
(`YYYY-MM-DDTHH:MM:SSZ`).
type: string
format: date-time
updated_on:
example: '2025-10-01T12:45:00.000Z'
description: >-
The timestamp of the most recent update to the file, in ISO 8601
format (`YYYY-MM-DDTHH:MM:SSZ`).
type: string
format: date-time
status:
description: >-
The current state of the uploaded file. Possible values:
- `Processing`: File is being processed (parsed, chunked, embedded)
- `Available`: Processing completed successfully; file is ready for
use
- `Deleting`: Deletion has been initiated but not yet completed
- `ProcessingFailed`: Processing failed with an error
Note: Once a file is deleted, the API returns 404 Not Found instead
of a file object.
x-enum:
- Processing
- Available
- Deleting
- ProcessingFailed
type: string
signed_url:
nullable: true
example: https://storage.googleapis.com/bucket/file.pdf?...
description: >-
A [signed
URL](https://cloud.google.com/storage/docs/access-control/signed-urls)
that provides temporary, read-only access to the file. Anyone with
the link can access the file, so treat it as sensitive data. Expires
after a short time.
type: string
multimodal:
description: Indicates whether the file was processed as multimodal.
type: boolean
required:
- id
- name
ImageModel:
nullable: true
description: Represents the data for an image.
type: object
properties:
type:
description: The format of the image data. Only `base64` is supported.
type: string
mime_type:
description: The MIME type of the image (e.g., `image/jpeg`).
type: string
data:
description: >-
The image data. When `type` is `base64`, this is a base64-encoded
string.
type: string
required:
- type
- mime_type
- data
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: Pinecone API Key
````