OpenAPI Specification
openapi: 3.0.3
info:
title: Pinecone Admin API Keys 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: API Keys
description: Actions that manage API Keys.
paths:
/admin/projects/{project_id}/api-keys:
get:
tags:
- API Keys
summary: List API keys
description: List all API keys in a project.
operationId: list_project_api_keys
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: project_id
description: Project ID
required: true
schema:
type: string
format: uuid
style: simple
responses:
'200':
description: A list of API keys.
content:
application/json:
schema:
$ref: '#/components/schemas/ListApiKeysResponse'
'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
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
- API Keys
summary: Create an API key
description: 'Create a new API key for a project. Developers can use the API key to authenticate requests to Pinecone''s Data Plane and Control Plane APIs.
'
operationId: create_api_key
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: project_id
description: Project ID
required: true
schema:
type: string
format: uuid
style: simple
requestBody:
description: The details of the new API key.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAPIKeyRequest'
required: true
responses:
'201':
description: API key created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/APIKeyWithSecret'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-metric-validation-error:
summary: Validation error
value:
error:
code: INVALID_ARGUMENT
message: Bad request. The request body included invalid request parameters.
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
'403':
description: Not enough available quota to complete this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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
/admin/api-keys/{api_key_id}:
get:
tags:
- API Keys
summary: Get API key details
description: Get the details of an API key, excluding the API key secret.
operationId: fetch_api_key
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: api_key_id
description: API key ID
required: true
schema:
type: string
format: uuid
style: simple
responses:
'200':
description: The details of the API key, excluding the API key secret.
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
'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: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
- API Keys
summary: Delete an API key
description: Delete an API key from a project.
operationId: delete_api_key
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: api_key_id
description: API key ID
required: true
schema:
type: string
format: uuid
style: simple
responses:
'202':
description: API key deletion request 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
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
- API Keys
summary: Update an API key
description: 'Update the name and roles of an API key.
'
operationId: update_api_key
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: api_key_id
description: API key ID
required: true
schema:
type: string
format: uuid
style: simple
requestBody:
description: Updated name and roles for the API key.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAPIKeyRequest'
required: true
responses:
'200':
description: API key updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-metric-validation-error:
summary: Validation error
value:
error:
code: INVALID_ARGUMENT
message: Bad request. The request body included invalid request parameters.
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
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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:
ListApiKeysResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/APIKey'
required:
- data
APIKeyWithSecret:
description: 'The details of an API key, including the secret. Only returned on API key creation.
'
type: object
properties:
key:
$ref: '#/components/schemas/APIKey'
value:
description: 'The value to use as an API key. New keys will have the format `"pckey_<public-label>_<unique-key>"`. The entire string should be used when authenticating.
'
type: string
required:
- key
- value
APIKey:
description: The details of an API key, without the secret.
type: object
properties:
id:
description: The unique ID of the API key.
type: string
format: uuid
name:
description: The name of the API key.
type: string
project_id:
description: The ID of the project containing the API key.
type: string
format: uuid
roles:
description: The roles assigned to the API key.
type: array
items:
example: ProjectEditor
description: 'A role that can be assigned to an API key.
Possible values: `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, or `DataPlaneViewer`.'
x-enum:
- ProjectEditor
- ProjectViewer
- ControlPlaneEditor
- ControlPlaneViewer
- DataPlaneEditor
- DataPlaneViewer
type: string
required:
- id
- name
- project_id
- roles
UpdateAPIKeyRequest:
type: object
properties:
name:
example: devkey
description: 'A new name for the API key. The name must be 1-80 characters long. If omitted, the name will not be updated.
'
type: string
minLength: 1
maxLength: 80
roles:
description: 'A new set of roles for the API key. Existing roles will be removed if not included.
If this field is omitted, the roles will not be updated.
'
type: array
items:
example: ProjectEditor
description: 'A role that can be assigned to an API key.
Possible values: `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, or `DataPlaneViewer`.'
x-enum:
- ProjectEditor
- ProjectViewer
- ControlPlaneEditor
- ControlPlaneViewer
- DataPlaneEditor
- DataPlaneViewer
type: string
CreateAPIKeyRequest:
type: object
properties:
name:
example: devkey
description: 'The name of the API key. The name must be 1-80 characters long.
'
type: string
minLength: 1
maxLength: 80
roles:
description: 'The roles to create the API key with. Default is `["ProjectEditor"]`.
'
type: array
items:
example: ProjectEditor
description: 'A role that can be assigned to an API key.
Possible values: `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, or `DataPlaneViewer`.'
x-enum:
- ProjectEditor
- ProjectViewer
- ControlPlaneEditor
- ControlPlaneViewer
- DataPlaneEditor
- DataPlaneViewer
type: string
required:
- name
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: Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen.
description: Detailed information about the error that occurred.
type: object
properties:
code:
description: 'The error code.
Possible values: `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`, or `UNPROCESSABLE_ENTITY`. '
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
- UNPROCESSABLE_ENTITY
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
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.
'