> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Repoint a namespace alias

> Update the namespace an alias resolves to. The change is atomic: the target
is validated in the same transaction that rewrites the alias, and on
failure the alias keeps its current target.

The call returns once the new target is live on every reader, which takes
about a second; size client timeouts accordingly. Reads through the alias
that start after the response are served from the new namespace, so no
polling is needed. Repointing is safe to retry; `updated_at` advances on
every attempt.

For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases).

<RequestExample>
  ```bash curl theme={null}
  # 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"
  ALIAS_NAME="dataset"

  curl -X PATCH "https://$INDEX_HOST/namespace-aliases/$ALIAS_NAME" \
      -H "Api-Key: $PINECONE_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Pinecone-Api-Version: 2026-07" \
      -d '{
          "target_namespace": "dataset_v2"
      }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml patch /namespace-aliases/{alias_name}
openapi: 3.0.3
info:
  title: Pinecone Data Plane API
  description: >-
    Pinecone is a vector database that makes it easy to search and retrieve
    billions of high-dimensional vectors.
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 2026-07
servers:
  - url: https://{index_host}
    variables:
      index_host:
        default: unknown
        description: host of the index
security:
  - ApiKeyAuth: []
tags:
  - name: Vector Operations
  - name: Bulk Operations
  - name: Namespace Operations
  - name: Namespace Alias Operations
  - name: Document Operations
    description: >-
      Operations on documents in an index created with a document schema — one
      that declares at least one full-text-searchable string field or a
      `dense_vector` / `sparse_vector` field under a name other than the
      reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
      document schema. Indexes served by the vectors API — created from
      `dimension`/`metric` on an earlier API version, or from a schema holding
      only the reserved vector fields and metadata — and indexes served by the
      records API — created with an integrated embedding model, whose schema
      holds a single `semantic_text` field — reject every document operation
      with `400` and name the API to use instead. A document index accepts only
      the document operations; the vector data operations (upsert, query, fetch,
      update, delete, list) reject it, while index stats and the namespace
      operations remain available.
externalDocs:
  description: More Pinecone.io API docs
  url: https://docs.pinecone.io/introduction
paths:
  /namespace-aliases/{alias_name}:
    parameters:
      - in: path
        name: alias_name
        description: >-
          The name of the alias. Must be 1-512 characters of printable ASCII,
          excluding space and `/ ? # % & = \ ; +`.
        required: true
        schema:
          type: string
          pattern: >-
            ^[\x21\x22\x24\x27-\x2A\x2C-\x2E\x30-\x3A\x3C\x3E\x40-\x5B\x5D-\x7E]+$
          minLength: 1
          maxLength: 512
        style: simple
    patch:
      tags:
        - Namespace Alias Operations
      summary: Repoint a namespace alias
      description: >-
        Update the namespace an alias resolves to. The change is atomic: the
        target

        is validated in the same transaction that rewrites the alias, and on

        failure the alias keeps its current target.


        The call returns once the new target is live on every reader, which
        takes

        about a second; size client timeouts accordingly. Reads through the
        alias

        that start after the response are served from the new namespace, so no

        polling is needed. Repointing is safe to retry; `updated_at` advances on

        every attempt.


        For guidance and examples, see [Manage namespace
        aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases).
      operationId: repointNamespaceAlias
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepointNamespaceAliasRequest'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceAliasDescription'
        '400':
          description: >-
            Bad request. The `reason` field of the error's `details` entry
            identifies the cause: `ALIAS_NAME_INVALID` (the alias name is
            invalid), `TARGET_NAMESPACE_REQUIRED` (`target_namespace` is missing
            or empty), `NAMESPACE_TOO_LONG` or `NAMESPACE_INVALID` (the target
            is not a possible namespace name), `TARGET_NAMESPACE_NOT_FOUND` (the
            target namespace does not exist), `TARGET_NAMESPACE_NOT_ACTIVE` (the
            target namespace is not active yet; the same request succeeds once
            it is), `TARGET_IS_ALIAS` (the target is itself an alias), or
            `API_VERSION_TOO_OLD` (the API version is too old).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '401':
          description: 'Unauthorized. Possible causes: missing or invalid API key.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedMessage'
        '404':
          description: Not found. No alias with this name exists in the index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        4XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
components:
  schemas:
    RepointNamespaceAliasRequest:
      description: A request for repointing a namespace alias at a different namespace.
      type: object
      properties:
        target_namespace:
          example: dataset_v2
          description: >-
            The namespace the alias resolves to after the repoint. 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__`.
          type: string
          pattern: ^[\x01-\x7F]+$
          minLength: 1
          maxLength: 512
      required:
        - target_namespace
    NamespaceAliasDescription:
      description: A description of a namespace alias and the namespace it resolves to.
      type: object
      properties:
        name:
          example: dataset
          description: The name of the alias. Immutable after creation.
          type: string
        target_namespace:
          example: dataset_v1
          description: >-
            The namespace the alias resolves to. Changed only by repointing the
            alias. The default namespace is represented as `__default__`.
          type: string
        created_at:
          example: '2026-09-01T12:00:00.000Z'
          description: The time the alias was created.
          type: string
          format: date-time
        updated_at:
          example: '2026-09-01T12:00:00.000Z'
          description: >-
            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.
          type: string
          format: date-time
      required:
        - name
        - target_namespace
        - created_at
        - updated_at
    rpcStatus:
      description: >-
        The error response shape returned by the vector and bulk operations.
        Requests rejected by the authentication and rate-limiting layer before
        they reach the service (`401`, and the `400`, `403`, and `429` it
        produces) return a plain-text body instead.
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    UnauthorizedMessage:
      example: Unauthorized
      description: >-
        The plain-text body of a `401` response. Authentication failures are
        rejected before the request reaches the index, so they carry the message
        `Unauthorized` rather than an error object.
      type: string
    protobufAny:
      type: object
      properties:
        typeUrl:
          type: string
        value:
          type: string
          format: byte
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: >-
        An API Key is required to call Pinecone APIs. Get yours from the
        [console](https://app.pinecone.io/).

````