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.
# 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"
}'POST /namespace-aliases
{
"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": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}Authorizations
Section titled “Authorizations”Api-KeystringrequiredAn API Key is required to call Pinecone APIs. Get yours from the console.
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
namestringrequiredThe 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. Example: dataset
target_namespacestringrequiredThe 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. Example: dataset_v1
Response
Section titled “Response”200 — A successful response.
A description of a namespace alias and the namespace it resolves to.
namestringrequiredThe name of the alias. Immutable after creation.
Example: dataset
target_namespacestringrequiredThe namespace the alias resolves to. Changed only by repointing the alias. The default namespace is represented as __default__.
Example: dataset_v1
created_atstringrequiredThe time the alias was created.
Example: 2026-09-01T12:00:00.000Z
updated_atstringrequiredThe 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