Admin API¶

The Admin API is used to manage your Pinecone organization and projects.

You will need to create a Pinecone service account to use the Pinecone Admin API.

class pinecone.Admin(client_id: str | None = None, client_secret: str | None = None, additional_headers: Dict[str, str] | None = None)[source]¶

A class for accessing the Pinecone Admin API.

A prerequisite for using this class is to have a service account. To create a service account, visit the Pinecone web console and navigate to the Access > Service Accounts section.

After creating a service account, you will be provided with a client ID and secret. These values can be passed to the Admin constructor or set the PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET environment variables.

Parameters:

client_id (Optional[str]) – The client ID for the Pinecone API. To obtain a client ID and secret, you must create a service account via the Pinecone web console. This value can be passed using keyword arguments or set the PINECONE_CLIENT_ID environment variable.
client_secret (Optional[str]) – The client secret for the Pinecone API. To obtain a client ID and secret, you must create a service account via the Pinecone web console. This value can be passed using keyword arguments or set the PINECONE_CLIENT_SECRET environment variable.
additional_headers (Optional[Dict[str, str]]) – Additional headers to use for the Pinecone API. This is a dictionary of key-value pairs. This is primarily used for internal testing purposes.

property api_key¶

A namespace for api key-related operations

Alias for api_keys().

To learn about all api key-related operations, see pinecone.admin.resources.ApiKeyResource().

Examples

Creating an API key¶

from pinecone import Admin

admin = Admin()

project = admin.project.get(name="my-project")

admin.api_key.create(
    name="my-api-key",
    project_id=project.id,
    description="my-api-key-description",
    roles=["ProjectEditor"]
)

Listing all API keys for a project¶

from pinecone import Admin

admin = Admin()
project = admin.project.get(name="my-project")
admin.api_key.list(project_id=project.id)

Deleting an API key¶

from pinecone import Admin

admin = Admin()
project = admin.project.get(name="my-project")

# List api keys for the project
keys_list = admin.api_key.list(project_id=project.id)

# Delete the first api key in the list
admin.api_key.delete(api_key_id=keys_list[0].id)

property api_keys¶: Alias for api_key()

property project¶

A namespace for project-related operations

Alias for projects().

To learn about all project-related operations, see pinecone.admin.resources.ProjectResource().

Examples

Creating a project¶

from pinecone import Admin

# Using environment variables to pass PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET
admin = Admin()

# Create a project with no quota for pod indexes
admin.project.create(
    name="my-project"
    max_pods=0
)

Listing all projects¶

from pinecone import Admin

admin = Admin()
admin.projects.list()

Deleting a project¶

from pinecone import Admin

admin = Admin()
project = admin.project.get(name="my-project")
admin.project.delete(project_id=project.id)

property projects¶: Alias for project()

Projects¶

class pinecone.admin.resources.ProjectResource(api_client: ApiClient)[source]¶

This class is used to create, delete, list, fetch, and update projects.

Note

The class should not be instantiated directly. Instead, access this classes methods through the pinecone.Admin class’s project or projects attributes.

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

# Now call project methods on the projects namespace
project = admin.projects.create(
    name="my-project",
    max_pods=10,
    force_encryption_with_cmek=False
)

create(name: str, max_pods: int | None = None, force_encryption_with_cmek: bool | None = None)[source]¶

Create a project.

Parameters:

name (str) – The name of the project to create.
max_pods (int) – The maximum number of pods for the project.
force_encryption_with_cmek (bool) – Whether to force encryption with CMEK.

Returns:

The created project.

Return type:

Project

Examples

Create a project¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.create(
    name="my-project-name",
    max_pods=10,
    force_encryption_with_cmek=False
)

print(project.id)
print(project.name)
print(project.organization_id)
print(project.max_pods)
print(project.force_encryption_with_cmek)
print(project.created_at)

delete(project_id: str, delete_all_indexes: bool = False, delete_all_collections: bool = False, delete_all_backups: bool = False)[source]¶

Warning

Deleting a project is a permanent and irreversible operation. Please be very sure you want to delete the project and everything associated with it before calling this function.

Projects can only be deleted if they are empty. The delete operation will fail if the project contains any resources such as indexes, collections, or backups.

If you pass additional options such as delete_all_indexes=True, delete_all_collections=True, or delete_all_backups=True, this function will attempt to delete all of these resources before deleting the project itself. These deletions are permanent and cannot be undone.

Parameters:

project_id (str) – The project_id of the project to delete.
delete_all_indexes (bool) – Attempt to delete all indexes associated with the project.
delete_all_collections (bool) – Attempt to delete all collections associated with the project.
delete_all_backups (bool) – Attempt to delete all backups associated with the project.

Returns:

None

Examples

Delete a project by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.get(name='my-project-name')

admin.project.delete(project_id=project.id)

Delete a project that still contains indexes, collections, and backups¶

from pinecone import Admin

admin = Admin()

project = admin.project.get(name='my-project-name')

admin.project.delete(
    project_id=project.id,
    delete_all_indexes=True,
    delete_all_collections=True,
    delete_all_backups=True
)

if not admin.project.exists(project_id=project.id):
    print("Project deleted successfully")
else:
    print("Project deletion failed")

describe(project_id: str | None = None, name: str | None = None)[source]¶

Alias for fetch()

Examples

Describe a project by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.describe(
    project_id="42ca341d-43bf-47cb-9f27-e645dbfabea6"
)
print(project.id)
print(project.name)
print(project.max_pods)
print(project.force_encryption_with_cmek)

exists(project_id: str | None = None, name: str | None = None)[source]¶

Check if a project exists by project_id or name.

Parameters:

project_id (str) – The project_id of the project to check.
name (str) – The name of the project to check.

Returns:

True if the project exists, False otherwise.

Return type:

bool

Raises:

ValueError – If both project_id and name are provided.

Examples

Check if a project exists by project name¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project_name = "my-project-name"
if admin.project.exists(name=project_name):
    print(f"Project {project_name} exists")
else:
    admin.project.create(
        name=project_name,
        max_pods=10,
        force_encryption_with_cmek=False
    )

Check if a project exists by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project_id = "42ca341d-43bf-47cb-9f27-e645dbfabea6"
if admin.project.exists(project_id=project_id):
    print(f"Project {project_id} exists")
else:
    print(f"Project {project_id} does not exist")

fetch(project_id: str | None = None, name: str | None = None)[source]¶

Fetch a project by project_id or name.

Parameters:

project_id (str) – The project_id of the project to fetch.
name (str) – The name of the project to fetch.

Returns:

The project.

Return type:

Project

Examples

Fetch a project by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.projects.fetch(
    project_id="42ca341d-43bf-47cb-9f27-e645dbfabea6"
)
print(project.id)
print(project.name)
print(project.max_pods)
print(project.force_encryption_with_cmek)
print(project.organization_id)
print(project.created_at)

Fetch a project by name¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.projects.fetch(name="my-project-name")
print(project.id)
print(project.name)
print(project.max_pods)
print(project.force_encryption_with_cmek)
print(project.organization_id)
print(project.created_at)

get(project_id: str | None = None, name: str | None = None)[source]¶

Alias for fetch()

Examples

Get a project by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.get(
    project_id="42ca341d-43bf-47cb-9f27-e645dbfabea6"
)
print(project.id)
print(project.name)
print(project.max_pods)
print(project.force_encryption_with_cmek)

list()[source]¶

List all projects in the organization.

Returns:: An object with a list of projects.
Return type:: {“data”: [Project]}

List all projects in the organization¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

# List all projects in the organization
projects_response = admin.projects.list()
for project in projects_response.data:
    print(project.id)
    print(project.name)
    print(project.max_pods)
    print(project.force_encryption_with_cmek)

update(project_id: str, name: str | None = None, max_pods: int | None = None, force_encryption_with_cmek: bool | None = None)[source]¶

Update a project.

Parameters:

project_id (str) – The project_id of the project to update.
name (str) – The name of the project to update.
max_pods (int) – The maximum number of pods for the project.
force_encryption_with_cmek (bool) – Whether to force encryption with CMEK.

Returns:

The updated project.

Return type:

Project

Examples

Update a project by project_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.get(name='my-project-name')

# Update max pods to 10
project = admin.project.update(
    project_id=project.id,
    max_pods=10
)

# Update force_encryption_with_cmek to True
project = admin.project.update(
    project_id=project.id,
    force_encryption_with_cmek=True
)

API Keys¶

class pinecone.admin.resources.ApiKeyResource(api_client: ApiClient)[source]¶

This class is used to create, delete, list, and fetch API keys.

Note

The class should not be instantiated directly. Instead, access this classes methods through the pinecone.Admin class’s api_key or api_keys attributes.

from pinecone import Admin

admin = Admin()

project = admin.project.get(name='my-project-name')
api_keys = admin.api_keys.list(project_id=project.id)

create(project_id: str, name: str, description: str | None = None, roles: List[str] | None = None)[source]¶

Create an API key for a project.

The value of the API key is returned in the create response. This is the only time the value is returned.

Parameters:

project_id (str) – The project_id of the project to create the API key for.
name (str) – The name of the API key.
description (Optional[str]) – The description of the API key.
roles (Optional[List[str]]) – The roles of the API key. Available roles include: ProjectEditor, ProjectViewer, ControlPlaneEditor, ControlPlaneViewer, DataPlaneEditor, DataPlaneViewer

Returns:

The created API key object and value.

Return type:

{“key”: APIKey, “value”: str}

Examples

Create an API key for a project¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.get(name='my-project-name')

api_key_response = admin.api_key.create(
    project_id=project.id,
    name='ci-key',
    description='Key for CI testing',
    roles=['ProjectEditor']
)
api_key = api_key_response.key
print(api_key.id)
print(api_key.name)
print(api_key.description)
print(api_key.roles)

api_key_value = api_key_response.value
print(api_key_value)

delete(api_key_id: str)[source]¶

Delete an API key by api_key_id.

Parameters:: api_key_id (str) – The id of the API key to delete.
Returns:: None

Examples

Delete an API key by api_key_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

admin.api_key.delete(api_key_id='my-api-key-id')

try:
    admin.api_key.fetch(api_key_id='my-api-key-id')
except NotFoundException:
    print("API key deleted successfully")

describe(api_key_id: str)[source]¶: Alias for fetch()

fetch(api_key_id: str)[source]¶

Fetch an API key by api_key_id.

The value of the API key is not returned. The value is only returned when a new API key is being created.

Parameters:: api_key_id (str) – The id of the API key to fetch.
Returns:: The API key.
Return type:: APIKey

Examples

Fetch an API key by api_key_id¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

api_key = admin.api_key.fetch(api_key_id='my-api-key-id')
print(api_key.id)
print(api_key.name)
print(api_key.description)
print(api_key.roles)
print(api_key.created_at)

get(api_key_id: str)[source]¶: Alias for fetch()

list(project_id: str)[source]¶

List all API keys for a project.

To find the project_id for your project, use pinecone.admin.resources.ProjectResource.list() or pinecone.admin.resources.ProjectResource.get().

The value of the API key is not returned. The value is only returned when a new API key is being created.

Parameters:: project_id (str) – The project_id of the project to list API keys for.
Returns:: An object with a list of API keys.
Return type:: {“data”: [APIKey]}

Examples

List all API keys for a project¶

from pinecone import Admin

# Credentials read from PINECONE_CLIENT_ID and
# PINECONE_CLIENT_SECRET environment variables
admin = Admin()

project = admin.project.get(name='my-project-name')

api_keys = admin.api_key.list(project_id=project.id)
for api_key in api_keys.data:
    print(api_key.id)
    print(api_key.name)
    print(api_key.description)
    print(api_key.roles)

Navigation

Related Topics

Admin API¶

Projects¶

API Keys¶