Pinecone Manage Assistants API

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 

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinecone/refs/heads/main/openapi/pinecone-manage-assistants-api-openapi.yml