Skip to main content
POST
/
namespaces
# 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: 2025-10" \
  -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": "0",
    "schema": {
        "fields": {
            "document_title": {
                "filterable": true
            },
            "document_url": {
                "filterable": true
            },
            "chunk_number": {
                "filterable": true
            },
            "document_id": {
                "filterable": true
            },
            "created_at": {
                "filterable": true
            }
        }
    }
}

# 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: 2025-10" \
  -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": "0",
    "schema": {
        "fields": {
            "document_title": {
                "filterable": true
            },
            "document_url": {
                "filterable": true
            },
            "chunk_number": {
                "filterable": true
            },
            "document_id": {
                "filterable": true
            },
            "created_at": {
                "filterable": true
            }
        }
    }
}

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:2025-10
required

Required date-based version header

Body

application/json

A request for creating a namespace with the specified namespace name.

​
name
string
required

The name of the namespace.

Example:

"example-namespace"

​
schema
object

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.

Example:
{
  "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.

​
name
string

The name of the namespace.

Example:

"example-namespace"

​
record_count
integer

The total amount of records within the namespace.

Example:

20000

​
schema
object

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.

Example:
{
  "fields": {
    "description": { "filterable": true },
    "genre": { "filterable": true },
    "year": { "filterable": true }
  }
}
​
total_count
integer

The total number of namespaces in the index matching the prefix

Example:

25

⌘I