# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X POST "https://$INDEX_HOST/namespace-aliases" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
        "name": "dataset",
        "target_namespace": "dataset_v1"
    }'

{
  "name": "dataset",
  "target_namespace": "dataset_v1",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z"
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

"Unauthorized"

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

Namespace aliases

Create a namespace alias

Create an alias that resolves to an existing namespace in the index. Reads through the alias are served from its target namespace; writes to an alias name are rejected. Many aliases can resolve to the same namespace.

The call returns once the alias resolves on every reader, which takes about a second; size client timeouts accordingly. A 409 whose details.metadata.target_namespace matches the requested target carries the same guarantee: your earlier call committed and the alias is live.

For guidance and examples, see Manage namespace aliases.

POST

namespace-aliases

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X POST "https://$INDEX_HOST/namespace-aliases" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
        "name": "dataset",
        "target_namespace": "dataset_v1"
    }'

{
  "name": "dataset",
  "target_namespace": "dataset_v1",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z"
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

"Unauthorized"

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "aSDinaTvuI8gbWludGxpZnk="
    }
  ]
}

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X POST "https://$INDEX_HOST/namespace-aliases" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
        "name": "dataset",
        "target_namespace": "dataset_v1"
    }'

Authorizations

Api-Key

string

header

required

An API Key is required to call Pinecone APIs. Get yours from the console.

Headers

X-Pinecone-Api-Version

string

default:2026-07

required

Required date-based version header

Body

application/json

A request for creating a namespace alias.

name

string

required

The name of the alias to create. Must be 1-512 characters of printable ASCII, excluding space and / ? # % & = \ ; +, and cannot be __default__, . or ... It shares one uniqueness space with namespace names: it cannot be the name of an existing namespace or alias, and no namespace can later be created under it.

Required string length: 1 - 512

Pattern: ^[\x21\x22\x24\x27-\x2A\x2C-\x2E\x30-\x3A\x3C\x3E\x40-\x5B\x5D-\x7E]+$

Example:

"dataset"

target_namespace

string

required

The namespace the alias resolves to. Must be an existing, active namespace in the index; an alias cannot point to another alias. To point the alias at the default namespace, use __default__.

Required string length: 1 - 512

Pattern: ^[\x01-\x7F]+$

Example:

"dataset_v1"

Response

A successful response.

A description of a namespace alias and the namespace it resolves to.

name

string

required

The name of the alias. Immutable after creation.

Example:

"dataset"

target_namespace

string

required

The namespace the alias resolves to. Changed only by repointing the alias. The default namespace is represented as __default__.

Example:

"dataset_v1"

created_at

string<date-time>

required

The time the alias was created.

Example:

"2026-09-01T12:00:00.000Z"

updated_at

string<date-time>

required

The time the alias was last repointed. Advances on every repoint, including a repoint to the alias's current target; equals created_at until the first repoint.

Example:

"2026-09-01T12:00:00.000Z"

APIs

Database

Inference

Admin

SDKs

CLI

Tools

Create a namespace alias

Authorizations

Headers

Body

Response