openapi: 3.0.3
info:
  title: Pinecone Admin API Keys Manage Assistants API
  description: 'Provides an API for managing a Pinecone organization and its resources.

    '
  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: 2025-10
servers:
- url: https://api.pinecone.io
  description: Production API endpoints
security:
- BearerAuth: []
tags:
- name: Manage Assistants
  description: Actions that manage Assistants
paths:
  /assistants:
    get:
      tags:
      - Manage Assistants
      summary: List assistants
      description: 'List of all assistants in a project.


        For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#list-assistants-for-a-project).'
      operationId: list_assistants
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      responses:
        '200':
          description: List all assistants in a project.
          content:
            application/json:
              schema:
                description: The list of assistants that exist in the project.
                type: object
                properties:
                  assistants:
                    type: array
                    items:
                      $ref: '#/components/schemas/Assistant'
        '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
        '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
    post:
      tags:
      - Manage Assistants
      summary: Create an assistant
      description: 'Create an assistant. This is where you specify the underlying training model, which cloud provider you would like to deploy with, and more.


        For guidance and examples, see [Create an assistant](https://docs.pinecone.io/guides/assistant/create-assistant)'
      operationId: create_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      requestBody:
        description: The desired configuration to create an assistant.
        content:
          application/json:
            schema:
              description: The configuration needed to create an assistant.
              type: object
              properties:
                name:
                  example: example-assistant
                  description: 'The name of the assistant. Resource name must be 1-63 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or ''-''.

                    '
                  type: string
                  minLength: 1
                  maxLength: 63
                instructions:
                  nullable: true
                  description: Description or directive for the assistant to apply to all responses. Maximum 16 KB.
                  type: string
                metadata:
                  description: Optional metadata associated with the assistant. Metadata is a JSON object that can store custom organizational data, tags, and attributes. Maximum size is 16KB.
                  type: object
                region:
                  description: The region to deploy the assistant in. Our current options are either us or eu. Defaults to us.
                  x-enum:
                  - us
                  - eu
                  type: string
              required:
              - name
        required: true
      responses:
        '200':
          description: Create request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                upload-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
        '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
        '429':
          description: Assistant of given name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /assistants/{assistant_name}:
    get:
      tags:
      - Manage Assistants
      summary: Check assistant status
      description: 'Get the status of an assistant.


        For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#get-the-status-of-an-assistant)'
      operationId: get_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to get a status on.
        required: true
        schema:
          type: string
        example: test-model
        style: simple
      responses:
        '200':
          description: Poll request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
        '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
    delete:
      tags:
      - Manage Assistants
      summary: Delete an assistant
      description: 'Delete an existing assistant.


        For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#delete-an-assistant)'
      operationId: delete_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to delete.
        required: true
        schema:
          type: string
        example: my-assistant
        style: simple
      responses:
        '200':
          description: The request to delete the assistant has been accepted.
        '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
    patch:
      tags:
      - Manage Assistants
      summary: Update an assistant
      description: 'Update an existing assistant. You can modify the assistant''s instructions.


        For guidance and examples, see [Manage assistants](https://docs.pinecone.io/guides/assistant/manage-assistants#add-instructions-to-an-assistant).'
      operationId: update_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to update.
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        description: The desired configuration updates for the assistant.
        content:
          application/json:
            schema:
              description: The configuration updates for the assistant.
              type: object
              properties:
                instructions:
                  nullable: true
                  description: Description or directive for the assistant to apply to all responses. Maximum 16 KB.
                  type: string
                metadata:
                  description: Optional metadata associated with the assistant. Metadata is a JSON object that can store custom organizational data, tags, and attributes. Maximum size is 16KB.
                  nullable: true
                  type: object
        required: true
      responses:
        '200':
          description: Update request successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assistant_name:
                    type: string
                  instructions:
                    description: Description or directive for the assistant to apply to all responses.
                    type: string
                  metadata:
                    description: Optional metadata associated with the assistant. Metadata is a JSON object that can store custom organizational data, tags, and attributes.
                    type: object
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Assistant not found
        '500':
          description: Internal Server Error
  /files/{assistant_name}:
    get:
      tags:
      - Manage Assistants
      summary: List Files
      description: 'List all files in an assistant, with an option to filter files with metadata.


        For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#list-files-in-an-assistant).'
      operationId: list_files
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to list files for.
        required: true
        schema:
          type: string
        example: test-assistant
        style: simple
      - in: query
        name: filter
        description: Optional JSON-encoded metadata filter for files.
        schema:
          type: string
          format: json
        example: '{"genre":{"$eq":"comedy"}}'
        style: form
      responses:
        '200':
          description: This operation returns a list of all files that you have previously uploaded, and which are associated with the given assistant name.
          content:
            application/json:
              schema:
                description: The list of files that exist in the assistant
                type: object
                properties:
                  files:
                    type: array
                    items:
                      $ref: '#/components/schemas/AssistantFileModel'
        '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
    post:
      tags:
      - Manage Assistants
      summary: Upload file to assistant
      description: 'Upload a file to the specified assistant.


        For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#upload-a-local-file).'
      operationId: upload_file
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to upload files to.
        required: true
        schema:
          type: string
        example: test-model
        style: simple
      - in: query
        name: metadata
        description: Optional JSON-encoded metadata for files.
        schema:
          type: string
          format: json
        example: '{"genre":{"$eq":"comedy"}}'
        style: form
      - in: query
        name: multimodal
        description: Optional flag to opt in to multimodal file processing (PDFs only). Can be either `true` or `false`. Default is `false`.
        schema:
          type: string
        style: form
      requestBody:
        description: The desired file to be uploaded and processed into the assistant.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The file to upload.
                  type: string
                  format: binary
              required:
              - file
        required: true
      responses:
        '200':
          description: File upload has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantFileModel'
        '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
  /files/{assistant_name}/{assistant_file_id}:
    get:
      tags:
      - Manage Assistants
      summary: Describe a file upload
      description: 'Get the status and metadata of a file uploaded to an assistant.


        For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#get-the-status-of-a-file).'
      operationId: describe_file
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to upload files to.
        required: true
        schema:
          type: string
        example: test-model
        style: simple
      - in: path
        name: assistant_file_id
        description: The uuid of the file to be described.
        required: true
        schema:
          type: string
        example: 72490b32-46d9-4db1-b48b-666e9176d9be
        style: simple
      - in: query
        name: include_url
        description: Include the signed URL of the file in the response.
        schema:
          x-enum:
          - 'true'
          - 'false'
          type: string
        style: form
      responses:
        '200':
          description: Poll request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantFileModel'
        '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: File not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                file-not-found:
                  summary: File not found.
                  value:
                    error:
                      code: NOT_FOUND
                      message: File with id 72490b32-46d9-4db1-b48b-666e9176d9be  not found in provided assistant
                    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
    delete:
      tags:
      - Manage Assistants
      summary: Delete an uploaded file
      description: 'Delete an uploaded file from an assistant.


        For guidance and examples, see [Manage files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file).'
      operationId: delete_file
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          type: string
        style: simple
      - in: path
        name: assistant_name
        description: The name of the assistant to upload files to.
        required: true
        schema:
          type: string
        example: test-model
        style: simple
      - in: path
        name: assistant_file_id
        description: The uuid of the file to be described.
        required: true
        schema:
          type: string
        example: 72490b32-46d9-4db1-b48b-666e9176d9be
        style: simple
      responses:
        '200':
          description: The request to delete the file has been accepted.
        '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: File not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                file-not-found:
                  summary: File not found.
                  value:
                    error:
                      code: NOT_FOUND
                      message: File with id 72490b32-46d9-4db1-b48b-666e9176d9be  not found in provided assistant
                    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
  /chat/{assistant_name}/chat/completions:
    post:
      tags:
      - Manage Assistants
      summary: Chat through an OpenAI-compatible interface
      description: "Chat with an assistant. This endpoint is based on the OpenAI Chat Completion API, a commonly used and adopted API. \n\nIt is useful if you need inline citations or OpenAI-compatible responses, but has limited functionality compared to the standard chat interface.\n\nFor guidance and examples, see [Chat with an assistant](https://docs.pinecone.io/guides/assistant/chat-with-assistant)."
      operationId: chat_completion_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          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 chat an assistant.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCompletions'
        required: true
      responses:
        '200':
          description: Search request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionModel'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/StreamChatCompletionChunkModel'
        '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
  /chat/{assistant_name}:
    post:
      tags:
      - Manage Assistants
      summary: Chat with an assistant
      description: "Chat with an assistant and get back citations in structured form. \n\nThis is the recommended way to chat with an assistant, as it offers more functionality and control over the assistant's responses and references than the OpenAI-compatible chat interface.\n\nFor guidance and examples, see [Chat with an assistant](https://docs.pinecone.io/guides/assistant/chat-with-assistant)."
      operationId: chat_assistant
      parameters:
      - in: header
        name: X-Pinecone-Api-Version
        description: Required date-based version header
        required: true
        schema:
          default: 2025-10
          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 chat an assistant.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
        required: true
      responses:
        '200':
          description: Search request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatModel'
        '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
  /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: 2025-10
          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:
    TextSnippetModel:
      description: Represents a text context snippet.
      type: object
      properties:
        type:
          description: The type of context snippet.
          type: string
        content:
          type: string
        score:
          type: number
          format: float
        reference:
          $ref: '#/components/schemas/TypedReferenceModel'
      required:
      - type
      - content
      - score
      - reference
    ChoiceChunkModel:
      description: Describes a single choice in a chat completion response.
      type: object
      properties:
        finish_reason:
          x-enum:
          - stop
          - length
          - content_filter
          - function_call
          type: string
        index:
          type: integer
        delta:
          description: Chat completion message
          type: object
          properties:
            role:
              type: string
            content:
              type: string
    DocxReferenceModel:
      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:
          type: array
          items:
            type: integer
      required:
      - type
      - file
      - pages
    Assistant:
      description: Describes the configuration and status of a Pinecone Assistant.
      type: object
      properties:
        name:
          example: example-assistant
          description: 'The name of the assistant. Resource name must be 1-63 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or ''-''.

            '
          type: string
          minLength: 1
          maxLength: 63
        instructions:
          nullable: true
          description: Description or directive for the assistant to apply to all responses.
          type: string
        metadata:
          description: Optional metadata associated with the assistant. Metadata is a JSON object that can store custom organizational data, tags, and attributes.
          nullable: true
          type: object
        status:
          x-enum:
          - Initializing
          - Failed
          - Ready
          - Terminating
          - InitializationFailed
          type: string
        host:
          description: The host where the assistant is deployed.
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - name
      - status
    SearchCompletions:
      description: The list of queries / chats to chat an assistant
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageModel'
        stream:
          description: If false, the assistant will return a single JSON response. If true, the assistant will return a stream of responses.
          default: false
          type: boolean
        model:
          description: The large language model to use for answer generation
          default: gpt-4o
          x-enum:
          - gpt-4o
          - gpt-4.1
          - o4-mini
          - claude-3-5-sonnet
          - claude-3-7-sonnet
          - gemini-2.5-pro
          type: string
        temperature:
          description: 'Controls the randomness of the model''s output: lower values make responses more deterministic, while higher values increase creativity and variability. If the model does not support a temperature parameter, the parameter will be ignored.'
          default: 0.0
          type: number
          format: float
        filter:
          example:
            genre:
              $ne: documentary
          description: Optionally filter which documents can be retrieved using the following metadata fields.
          type: object
      required:
      - messages
    MessageModel:
      description: Describes the format of a message in a chat.
      type: object
      properties:
        role:
          description: Role of the message such as 'user' or 'assistant'
          type: string
        content:
          description: Content of the message
          type: string
    ContextModel:
      description: The response format containing the context from an assistant.
      type: object
      properties:
        id:
          type: string
        snippets:
          type: array
          items:
            $ref: '#/components/schemas/SnippetModel'
        usage:
          $ref: '#/components/schemas/UsageModel'
      required:
      - snippets
      - usage
    JsonReferenceModel:
      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
    StreamChatCompletionChunkModel:
      description: Describes the response format of a chat request.
      type: object
      properties:
        id:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChoiceChunkModel'
        model:
          type: string
    ImageModel:
      nullable: true
      description: Represents the data for an image.
      type: object
      properties:
        type:
          description: The format of the image data. Currently, this is always "base64".
          type: string
        mime_type:
          description: The MIME type of the image (e.g., "image/jpeg").
          type: string
        data:
          description: The image data. Currently, this is always a base64-encoded string.
          type: string
      required:
      - type
      - mime_type
      - data
    ChatModel:
      description: Describes the response format of a chat request from the citation API.
      type: object
      properties:
        id:
          type: string
        finish_reason:
          x-enum:
          - stop
          - length
          - content_filter
          - function_call
          type: string
        message:
          $ref: '#/components/schemas/MessageModel'
        model:
          type: string
        citations:
          type: array
          items:
            $ref: '#/components/schemas/CitationModel'
        usage:
          $ref: '#/components/schemas/UsageModel'
    ErrorResponse:
      example:
        error:
          code: QUOTA_EXCEEDED
          message: The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota.
        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: Uploaded file can only currently be either a pdf or txt file
          description: Detailed information about the error that occurred.
          type: object
          properties:
            code:
              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
              type: string
            message:
              example: Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen.
              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
    HighlightModel:
      nullable: true
      description: Represents a portion of a referenced document that directly supports or is relevant to the response.
      type: object
      properties:
        type:
          description: The type of the highlight. Currently it is always text.
          type: string
        content:
          type: string
      required:
      - type
      - content
    UsageModel:
      description: Describes the usage of a chat completion.
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    MultiModalContentBlocksModel:
      description: Represents a block in the multimodal content of a context snippet.
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/MultiModalContentTextBlockModel'
          image: '#/components/schemas/MultiModalContentImageBlockModel'
      type: object
      oneOf:
      - $ref: '#/components/schemas/MultiModalContentTextBlockModel'
      - $ref: '#/components/schemas/MultiModalContentImageBlockModel'
    CitationModel:
      description: Describes a single cited source returned by a chat request.
      type: object
      properties:
        position:
          description: The index position of the citation in the complete text response.
          type: integer
        references:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceModel'
    SnippetModel:
      description: Represents a part of a document that is relevant to the user query.
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextSnippetModel'
          multimodal: '#/components/schemas/MultiModalSnippetModel'
      type: object
      oneOf:
      - $ref: '#/components/schemas/TextSnippetModel'
      - $ref: '#/components/schemas/MultiModalSnippetModel'
    PdfReferenceModel:
      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:
          type: array
          items:
            type: integer
      required:
      - type
      - file
      - pages
    AssistantFileModel:
      description: The response format for a successful file upload request.
      type: object
      properties:
        name:
          type: string
        id:
          type: string
          format: uuid
        metadata:
          nullable: true
          type: object
        created_on:
          type: string
          format: date-time
        updated_on:
          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
        percent_done:
          nullable: true
          description: The percentage of the file that has been processed
          type: number
          format: double
        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 underlying file. Anyone with the link can access the file, so treat it as sensitive data. Expires after a short time.
          type: string
        error_message:
          nullable: true
          description: A message describing any error during file processing. Provided only if an error occurs.
          type: string
        multimodal:
          description: Indicates whether the file was processed as multimodal.
          type: boolean
      required:
      - id
      - name
    MultiModalContentImageBlockModel:
      description: Represents an image block in a multimodal context snippet.
      type: object
      properties:
        type:
          description: The type of multimodal content block.
          type: string
        caption:
          type: string
        image:
          $ref: '#/components/schemas/ImageModel'
      required:
      - type
      - caption
    ChatCompletionModel:
      description: Describes the response format of a chat request.
      type: object
      properties:
        id:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChoiceModel'
        model:
          type: string
        usage:
          $ref: '#/components/schemas/UsageModel'
    ChoiceModel:
      description: Describes a single choice in a chat completion response.
      type: object
      properties:
        finish_reason:
          x-enum:
          - stop
          - length
          - content_filter
          - function_call
          type: string
        index:
          type: integer
        message:
          $ref: '#/components/schemas/MessageModel'
    TypedReferenceModel:
      description: Represents a reference for the information provided.
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextReferenceModel'
          json: '#/components/schemas/JsonReferenceModel'
          markdown: '#/components/schemas/MarkdownReferenceModel'
          pdf: '#/components/schemas/PdfReferenceModel'
          doc_x: '#/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'
    ContextOptionsModel:
      description: Controls the context snippets sent to the LLM.
      type: object
      properties:
        top_k:
          example: 20
          description: The maximum number of context snippets to use. 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 send image-related context snippets to the LLM. If `false`, only text context snippets are sent.
          default: true
          type: boolean
        include_binary_content:
          description: If image-related context snippets are sent to the LLM, this field determines whether or not they should include base64 image data. If `false`, only the image caption is sent. Only available when `multimodal=true`.
          default: true
          type: boolean
    MultiModalSnippetModel:
      description: Represents a multimodal context snippet.
      type: object
      properties:
        type:
          description: The type of context snippet.
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/MultiModalContentBlocksModel'
        score:
          type: number
          format: float
        reference:
          $ref: '#/components/schemas/TypedReferenceModel'
      required:
      - type
      - content
      - score
      - reference
    TextReferenceModel:
      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
    MarkdownReferenceModel:
      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
    MultiModalContentTextBlockModel:
      description: Represents a text block in a multimodal context snippet.
      type: object
      properties:
        type:
          description: The type of multimodal content block.
          type: string
        text:
          type: string
      required:
      - type
      - text
    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
    ChatRequest:
      description: The list of queries / chats to chat an assistant
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageModel'
        stream:
          description: If false, the assistant will return a single JSON response. If true, the assistant will return a stream of responses.
          default: false
          type: boolean
        model:
          description: The large language model to use for answer generation
          default: gpt-4o
          x-enum:
          - gpt-4o
          - gpt-4.1
          - o4-mini
          - claude-3-5-sonnet
          - claude-3-7-sonnet
          - gemini-2.5-pro
          type: string
        temperature:
          description: 'Controls the randomness of the model''s output: lower values make responses more deterministic, while higher values increase creativity and variability. If the model does not support a temperature parameter, the parameter will be ignored.'
          default: 0.0
          type: number
          format: float
        filter:
          example:
            genre:
              $ne: documentary
          description: Optionally filter which documents can be retrieved using the following metadata fields.
          type: object
        json_response:
          description: If true, the assistant will be instructed to return a JSON response. Cannot be used with streaming.
          default: false
          type: boolean
        include_highlights:
          description: If true, the assistant will be instructed to return highlights from the referenced documents that support its response.
          default: false
          type: boolean
        context_options:
          $ref: '#/components/schemas/ContextOptionsModel'
      required:
      - messages
    ReferenceModel:
      description: Describes a single reference in a citation.
      type: object
      properties:
        file:
          $ref: '#/components/schemas/AssistantFileModel'
        pages:
          type: array
          items:
            type: integer
        highlight:
          $ref: '#/components/schemas/HighlightModel'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'An [access token](https://docs.pinecone.io/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided in the `Authorization` header using the `Bearer` scheme.

        '