Create a namespace

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}
          }
        }
      }'

POST /namespaces

• X-Pinecone-Api-Version (header, string, required) — Required date-based version header

• name (body, string, required) — 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.
• schema (body, 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.

• 200 — A successful response.
• 400 — Bad request. The request body included invalid request parameters.
• 401 — Unauthorized. Possible causes: missing or invalid API key.
• 409 — Namespace of the given name already exists on the index.
• 4XX — An unexpected error response.
• 5XX — An unexpected error response.