Admin¶

The Admin client manages organizations, projects, and API keys. It uses OAuth2 client credentials (service account) rather than an API key, and is the right tool for control-plane operations such as creating projects and rotating keys.

class pinecone.admin.Admin(*, client_id=None, client_secret=None, additional_headers=None, proxy_url=None, ssl_verify=True, source_tag=None)[source]¶

Bases: object

Admin client for Pinecone organization and project management.

Authenticates via OAuth2 client credentials flow to obtain a Bearer token used for all admin API calls.

Auth model: Admin uses OAuth2 client credentials (service account), while Pinecone uses API keys. These serve different purposes:

Admin — organization/project/key management (create projects, rotate keys, etc.)
Pinecone — index and vector operations (upsert, query, etc.)

A common workflow bridges both: use Admin to create a project and API key, then pass that key to Pinecone for data-plane operations:

from pinecone import Admin, Pinecone, ServerlessSpec

admin = Admin(client_id="...", client_secret="...")
project = admin.projects.create(name="my-project")
key = admin.api_keys.create(project_id=project.id, name="my-key")
pc = Pinecone(api_key=key.value)
pc.indexes.create(name="my-index", dimension=1536, metric="cosine",
                  spec=ServerlessSpec(cloud="aws", region="us-east-1"))

Projects are created within the organization associated with your OAuth credentials.

Note

Obtaining OAuth credentials — Service account credentials (client_id and client_secret) are created in the Pinecone console:

Go to console.pinecone.io.
Navigate to Organization Settings → Service Accounts.
Click Create Service Account, assign the desired role, and save the generated client_id and client_secret.

These differ from the API keys used by Pinecone; they are scoped to your organization and used exclusively for admin operations.

Parameters:

client_id (str | None) – OAuth2 client ID. Falls back to PINECONE_CLIENT_ID env var.
client_secret (str | None) – OAuth2 client secret. Falls back to PINECONE_CLIENT_SECRET env var.
additional_headers (dict[str, str] | None) – Extra headers included in every admin API request.
proxy_url (str | None) – HTTP proxy URL for outgoing requests.
ssl_verify (bool) – Whether to verify SSL certificates. Defaults to True.
source_tag (str | None) – Tag appended to the User-Agent string for request attribution.

Raises:

PineconeValueError – If client_id or client_secret cannot be resolved.
ApiError – If the OAuth token request fails.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for org in admin.organizations.list():
...     print(org.name)

__init__(*, client_id=None, client_secret=None, additional_headers=None, proxy_url=None, ssl_verify=True, source_tag=None)[source]¶

Parameters:

client_id (str | None)
client_secret (str | None)
additional_headers (dict[str, str] | None)
proxy_url (str | None)
ssl_verify (bool)
source_tag (str | None)

Return type:

None

property api_keys: ApiKeys¶

Access the ApiKeys namespace for API key operations.

Lazily imported and instantiated on first access.

Returns:: ApiKeys namespace instance.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> keys = admin.api_keys.list(project_id="proj-abc123")
>>> for key in keys:
...     print(key.key.id)

close()[source]¶

Close the underlying HTTP client.

Return type:: None

property organizations: Organizations¶

Access the Organizations namespace for organization operations.

Lazily imported and instantiated on first access.

Returns:: Organizations namespace instance.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for org in admin.organizations.list():
...     print(org.name)

property projects: Projects¶

Access the Projects namespace for project operations.

Lazily imported and instantiated on first access.

Returns:: Projects namespace instance.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for project in admin.projects.list():
...     print(project.name)

Organizations¶

class pinecone.admin.organizations.Organizations(*, http)[source]¶

Bases: object

Control-plane operations for Pinecone organizations.

Provides methods to list, describe, update, and delete organizations.

Parameters:: http (HTTPClient) – HTTP client for making API requests.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="my-id", client_secret="my-secret")
>>> for org in admin.organizations.list():
...     print(org.name)

__init__(*, http)[source]¶

Parameters:: http (HTTPClient)
Return type:: None

delete(*, organization_id)[source]¶

Delete an organization.

Parameters:

organization_id (str) – The identifier of the organization to delete.

Raises:

PineconeValueError – If organization_id is empty.
ApiError – If the API returns an error response (e.g. 4xx if org has projects).

Return type:

None

Examples

>>> admin.organizations.delete(organization_id="org-abc123")

describe(*, organization_id)[source]¶

Get detailed information about an organization.

Parameters:

organization_id (str) – The identifier of the organization.

Returns:

An OrganizationModel with full organization details.

Raises:

PineconeValueError – If organization_id is empty.
ApiError – If the API returns an error response.

Return type:

OrganizationModel

Examples

>>> org = admin.organizations.describe(organization_id="org-abc123")
>>> org.name
'Acme Corp'

list()[source]¶

List all organizations accessible to the authenticated user.

Returns:: An OrganizationList supporting iteration, len(), and index access.
Raises:: ApiError – If the API returns an error response.
Return type:: OrganizationList

Examples

>>> admin = Admin(client_id="my-id", client_secret="my-secret")
>>> for org in admin.organizations.list():
...     print(org.name)

update(*, organization_id, name)[source]¶

Update an organization’s name.

Parameters:

organization_id (str) – The identifier of the organization to update.
name (str) – The new name for the organization.

Returns:

An OrganizationModel with the updated organization details.

Raises:

PineconeValueError – If organization_id or name is empty.
ApiError – If the API returns an error response.

Return type:

OrganizationModel

Examples

>>> org = admin.organizations.update(
...     organization_id="org-abc123", name="New Name"
... )
>>> org.name
'New Name'

Projects¶

class pinecone.admin.projects.Projects(*, http, admin=None)[source]¶

Bases: object

Control-plane operations for Pinecone projects.

Provides methods to list, create, describe, update, and delete projects.

Parameters:

http (HTTPClient) – HTTP client for making API requests.
admin (Admin | None)

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for project in admin.projects.list():
...     print(project.name)

__init__(*, http, admin=None)[source]¶

Parameters:

http (HTTPClient)
admin (Admin | None)

Return type:

None

create(*, name, max_pods=None, force_encryption_with_cmek=None)[source]¶

Create a new project.

Parameters:

name (str) – Name for the new project.
max_pods (int | None) – Maximum number of pods allowed. Omitted if None.
force_encryption_with_cmek (bool | None) – Whether to enforce CMEK encryption. Omitted if None.

Returns:

A ProjectModel with the created project details.

Raises:

PineconeValueError – If name is empty.
ApiError – If the API returns an error response.

Return type:

ProjectModel

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> project = admin.projects.create(name="my-project")
>>> project.name
'my-project'

delete(*, project_id)[source]¶

Delete a project.

Parameters:

project_id (str) – The identifier of the project to delete.

Raises:

PineconeValueError – If project_id is empty.
ApiError – If the API returns an error (project still has indexes or collections).

Return type:

None

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> admin.projects.delete(project_id="proj-abc123")

delete_with_cleanup(*, project_id, max_attempts=5, retry_delay=30.0)[source]¶

Delete a project after cleaning up all its resources.

Creates a temporary API key scoped to the project, uses it to delete all indexes, collections, and backups, then deletes the temporary key and finally deletes the project itself.

The cleanup is retried up to max_attempts times with retry_delay seconds between attempts to handle transient failures.

Parameters:

project_id (str) – The identifier of the project to delete.
max_attempts (int) – Maximum number of cleanup attempts. Defaults to 5.
retry_delay (float) – Seconds to wait between retry attempts. Defaults to 30.0.

Raises:

PineconeError – If no admin back-reference is available.
PineconeValueError – If project_id is empty.
ApiError – If resource cleanup or project deletion fails after all retries.

Return type:

None

Examples

from pinecone import Admin
admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
admin.projects.delete_with_cleanup(project_id="proj-abc123")

describe(*, project_id)[source]¶

Get detailed information about a project.

Parameters:

project_id (str) – The identifier of the project.

Returns:

A ProjectModel with full project details.

Raises:

PineconeValueError – If project_id is empty.
ApiError – If the API returns an error response.

Return type:

ProjectModel

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> project = admin.projects.describe(project_id="proj-abc123")
>>> project.name
'my-project'

describe_by_name(*, name)[source]¶

Get detailed information about a project by name.

Lists all projects and filters client-side for an exact name match.

Parameters:

name (str) – The name of the project.

Returns:

A ProjectModel with full project details.

Raises:

PineconeValueError – If name is empty.
NotFoundError – If no project matches name.
PineconeError – If multiple projects share name.

Return type:

ProjectModel

Examples

from pinecone import Admin
admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
project = admin.projects.describe_by_name(name="my-project")
project.id  # 'proj-abc123'

exists(*, project_id=None, name=None)[source]¶

Check whether a project exists.

Exactly one of project_id or name must be provided.

Parameters:

project_id (str | None) – The identifier of the project.
name (str | None) – The name of the project.

Returns:

True if the project exists, False otherwise.

Raises:

PineconeValueError – If neither or both arguments are provided.

Return type:

bool

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> admin.projects.exists(project_id="proj-abc123")
True
>>> admin.projects.exists(name="nonexistent")
False

list()[source]¶

List all projects accessible to the authenticated user.

Returns:: A ProjectList supporting iteration, len(), and index access.
Raises:: ApiError – If the API returns an error response.
Return type:: ProjectList

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for project in admin.projects.list():
...     print(project.name)

update(*, project_id, name=None, max_pods=None, force_encryption_with_cmek=None)[source]¶

Update a project’s settings.

Parameters:

project_id (str) – The identifier of the project to update.
name (str | None) – New name for the project.
max_pods (int | None) – New maximum pod count.
force_encryption_with_cmek (bool | None) – New CMEK enforcement setting.

Returns:

A ProjectModel with the updated project details.

Raises:

PineconeValueError – If project_id is empty.
ApiError – If the API returns an error response.

Return type:

ProjectModel

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> project = admin.projects.update(
...     project_id="proj-abc123", name="new-name"
... )
>>> project.name
'new-name'

API Keys¶

class pinecone.admin.api_keys.ApiKeys(*, http)[source]¶

Bases: object

Control-plane operations for Pinecone API keys.

Provides methods to list, create, describe, update, and delete API keys scoped to a project.

Parameters:: http (HTTPClient) – HTTP client for making API requests.

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for key in admin.api_keys.list(project_id="proj-abc123"):
...     print(key.name)

__init__(*, http)[source]¶

Parameters:: http (HTTPClient)
Return type:: None

create(*, project_id, name, description=None, roles=None)[source]¶

Create a new API key for a project.

Parameters:

project_id (str) – The identifier of the project.
name (str) – Name for the new API key (1-80 characters).
description (str | None) – Optional description for the API key.
roles (list[APIKeyRole | str] | None) – Roles to assign to the key. Valid values are "ProjectEditor", "ProjectViewer", "ControlPlaneEditor", "ControlPlaneViewer", "DataPlaneEditor", and "DataPlaneViewer". Defaults to ["ProjectEditor"] if omitted.

Returns:

An APIKeyWithSecret containing the key metadata and secret value. The secret value is only available at creation time.

Raises:

PineconeValueError – If project_id or name is empty.
ApiError – If the API returns an error response.

Return type:

APIKeyWithSecret

Examples

>>> from pinecone import Admin, APIKeyRole
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> result = admin.api_keys.create(
...     project_id="proj-abc123", name="prod-search-key",
...     roles=[APIKeyRole.PROJECT_EDITOR]
... )
>>> result.value
'pcsk_abc123_secretvalue'

>>> result = admin.api_keys.create(
...     project_id="proj-abc123", name="ci-pipeline-key", roles=["ProjectViewer"]
... )
>>> result.key.roles
['ProjectViewer']

delete(*, api_key_id)[source]¶

Delete an API key.

Parameters:

api_key_id (str) – The identifier of the API key to delete.

Raises:

PineconeValueError – If api_key_id is empty.
ApiError – If the API returns an error response.

Return type:

None

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> admin.api_keys.delete(api_key_id="key-abc123")

describe(*, api_key_id)[source]¶

Get detailed information about an API key.

Parameters:

api_key_id (str) – The identifier of the API key.

Returns:

An APIKeyModel with full API key details.

Raises:

PineconeValueError – If api_key_id is empty.
ApiError – If the API returns an error response.

Return type:

APIKeyModel

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> key = admin.api_keys.describe(api_key_id="key-abc123")
>>> key.name
'prod-search-key'

list(*, project_id)[source]¶

List all API keys for a project.

Parameters:

project_id (str) – The identifier of the project.

Returns:

An APIKeyList supporting iteration, len(), and index access.

Raises:

PineconeValueError – If project_id is empty.
ApiError – If the API returns an error response.

Return type:

APIKeyList

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> for key in admin.api_keys.list(project_id="proj-abc123"):
...     print(key.name)

update(*, api_key_id, name=None, roles=None)[source]¶

Update an API key’s settings.

When roles is provided, it replaces the entire role set.

Parameters:

api_key_id (str) – The identifier of the API key to update.
name (str | None) – New name for the API key.
roles (list[APIKeyRole | str] | None) – New roles for the API key. Replaces all existing roles.

Returns:

An APIKeyModel with the updated API key details.

Raises:

PineconeValueError – If api_key_id is empty.
ApiError – If the API returns an error response.

Return type:

APIKeyModel

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> key = admin.api_keys.update(
...     api_key_id="key-abc123", name="new-name"
... )
>>> key.name
'new-name'