# 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 "https://$INDEX_HOST/namespaces" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"name": "example-namespace",
"schema": {
"fields": {
"document_id": {"filterable": true},
"document_title": {"filterable": true},
"chunk_number": {"filterable": true},
"document_url": {"filterable": true},
"created_at": {"filterable": true}
}
}
}'
{
"name": "example-namespace",
"record_count": "20000",
"schema": {
"fields": {
"description": {
"filterable": true
},
"genre": {
"filterable": true
},
"year": {
"filterable": true
}
}
},
"indexed_fields": {
"fields": [
"genre",
"year",
"author"
]
},
"size_bytes": "1048576"
}{
"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="
}
]
}Create a namespace
Create a namespace in a serverless index.
For guidance and examples, see Manage namespaces.
Note: This operation is not supported for pod-based indexes.
# 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 "https://$INDEX_HOST/namespaces" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"name": "example-namespace",
"schema": {
"fields": {
"document_id": {"filterable": true},
"document_title": {"filterable": true},
"chunk_number": {"filterable": true},
"document_url": {"filterable": true},
"created_at": {"filterable": true}
}
}
}'
{
"name": "example-namespace",
"record_count": "20000",
"schema": {
"fields": {
"description": {
"filterable": true
},
"genre": {
"filterable": true
},
"year": {
"filterable": true
}
}
},
"indexed_fields": {
"fields": [
"genre",
"year",
"author"
]
},
"size_bytes": "1048576"
}{
"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 "https://$INDEX_HOST/namespaces" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"name": "example-namespace",
"schema": {
"fields": {
"document_id": {"filterable": true},
"document_title": {"filterable": true},
"chunk_number": {"filterable": true},
"document_url": {"filterable": true},
"created_at": {"filterable": true}
}
}
}'
Authorizations
Headers
Required date-based version header
Body
A request for creating a namespace with the specified namespace name.
The name of the namespace. Must be ASCII, must not contain the NUL character, and must be 1-512 characters long.
__default__ is reserved: it names the namespace requests address when they omit a namespace, so it always exists and cannot be created explicitly.
1 - 512^[\x01-\x7F]+$"example-namespace"
Schema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.
Show child attributes
Show child attributes
{
"fields": {
"description": { "filterable": true },
"genre": { "filterable": true },
"year": { "filterable": true }
}
}
Response
A successful response.
A description of a namespace, including the name and record count.
The name of the namespace.
"example-namespace"
The total number of records in the namespace. A 64-bit integer, serialized as a decimal string.
"20000"
Schema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.
Show child attributes
Show child attributes
{
"fields": {
"description": { "filterable": true },
"genre": { "filterable": true },
"year": { "filterable": true }
}
}
A list of all indexed metatadata fields in the namespace
Show child attributes
Show child attributes
The total size of the namespace's data, in bytes, as a 64-bit integer serialized as a decimal string. Approximate: data written before size tracking reads as 0, and recently deleted data may still be counted; compaction converges the value.
"1048576"
Was this page helpful?