turbopuffer Namespaces API

openapi: 3.2.0
info:
  title: turbopuffer Namespaces API
  version: 0.0.1
  description: turbopuffer is a fast search engine that combines vector and full-text search using object storage.
  termsOfService: https://turbopuffer.com/terms-of-service
  contact: info@turbopuffer.com
servers:
- url: https://{region}.turbopuffer.com
  description: Production API servers
  variables:
    region:
      description: The turbopuffer region to use.
security:
- bearerAuth: []
tags:
- name: Namespaces
paths:
  /v1/namespaces:
    get:
      description: List namespaces.
      parameters:
      - name: cursor
        in: query
        description: Retrieve the next page of results.
        schema:
          type: string
      - name: prefix
        in: query
        description: Retrieve only the namespaces that match the prefix.
        schema:
          type: string
      - name: page_size
        in: query
        description: Limit the number of results per page.
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: A JSON array of namespace metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  namespaces:
                    type: array
                    description: The list of namespaces.
                    items:
                      $ref: '#/components/schemas/NamespaceSummary'
                  next_cursor:
                    type: string
                    description: The cursor to use to retrieve the next page of results.
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v1/namespaces/{namespace}/schema:
    get:
      description: Get namespace schema.
      parameters:
      - $ref: '#/components/parameters/namespace'
      responses:
        '200':
          description: The schema of the namespace.
          content:
            application/json:
              schema:
                description: The response to a successful namespace schema request.
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/AttributeSchemaConfig'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
    post:
      description: Update namespace schema.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              description: The desired schema for the namespace.
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AttributeSchema'
      responses:
        '200':
          description: The schema of the namespace.
          content:
            application/json:
              schema:
                description: The updated schema for the namespace.
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/AttributeSchemaConfig'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}/metadata:
    get:
      description: Get metadata about a namespace.
      parameters:
      - $ref: '#/components/parameters/namespace'
      responses:
        '200':
          description: The metadata of the namespace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceMetadata'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v1/namespaces/{namespace}/metadata:
    patch:
      description: Update metadata configuration for a namespace.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamespaceMetadataPatch'
      responses:
        '200':
          description: The updated metadata of the namespace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceMetadata'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v1/namespaces/{namespace}/hint_cache_warm:
    get:
      description: Signal turbopuffer to prepare for low-latency requests.
      parameters:
      - $ref: '#/components/parameters/namespace'
      responses:
        '202':
          description: The status of the cache warm request.
          content:
            application/json:
              schema:
                description: The response to a successful cache warm request.
                type: object
                properties:
                  status:
                    const: ACCEPTED
                    description: The status of the request.
                  message:
                    type: string
                required:
                - status
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v1/namespaces/{namespace}/_debug/recall:
    post:
      description: Evaluate recall.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                num:
                  type: integer
                  description: The number of searches to run.
                top_k:
                  type: integer
                  description: Search for `top_k` nearest neighbors.
                filters:
                  x-stainless-any: true
                  description: Filter by attributes. Same syntax as the query endpoint.
                include_ground_truth:
                  type: boolean
                  description: Include ground truth data (query vectors and true nearest neighbors) in the response.
                  default: false
                rank_by:
                  description: 'The ranking function to evaluate recall for. If provided, `num` must be either null or 1.

                    '
                  x-stainless-any: true
      responses:
        '200':
          description: The status of the cache warm request.
          content:
            application/json:
              schema:
                description: The response to a successful cache warm request.
                type: object
                properties:
                  avg_recall:
                    description: The average recall of the queries.
                    type: number
                  avg_exhaustive_count:
                    description: The average number of documents retrieved by the exhaustive searches.
                    type: number
                  avg_ann_count:
                    description: The average number of documents retrieved by the approximate nearest neighbor searches.
                    type: number
                  ground_truth:
                    description: Ground truth data including query vectors and true nearest neighbors. Only included when include_ground_truth is true.
                    type: array
                    items:
                      type: object
                      properties:
                        query_vector:
                          description: The query vector used for this search.
                          type: array
                          items:
                            type: number
                        nearest_neighbors:
                          description: The true nearest neighbors with their distances and vectors.
                          type: array
                          items:
                            $ref: '#/components/schemas/Row'
                      required:
                      - query_vector
                      - nearest_neighbors
                required:
                - avg_recall
                - avg_exhaustive_count
                - avg_ann_count
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}:
    post:
      description: Create, update, or delete documents.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Write'
      responses:
        '200':
          description: The status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResult'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
    delete:
      description: Delete namespace.
      parameters:
      - $ref: '#/components/parameters/namespace'
      responses:
        '200':
          description: The status of the deletion request.
          content:
            application/json:
              schema:
                description: The response to a successful namespace deletion request.
                type: object
                properties:
                  status:
                    const: OK
                    description: The status of the request.
                required:
                - status
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}/query:
    post:
      description: Query, filter, full-text search and vector search documents.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/QueryConfig'
              - $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: The schema of the namespace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}/query?stainless_overload=multiQuery:
    post:
      description: Issue multiple concurrent queries filter or search documents.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/QueryConfig'
              - type: object
                required:
                - queries
                properties:
                  queries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: The schema of the namespace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiQueryResult'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}?stainless_overload=branchFrom:
    post:
      description: Creates an instant, copy-on-write clone of a namespace.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BranchFromNamespaceConfig'
      responses:
        '200':
          description: The status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResult'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}?stainless_overload=copyFrom:
    post:
      description: Copy all documents from another namespace into this one.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyFromNamespaceConfig'
      responses:
        '200':
          description: The status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResult'
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
  /v2/namespaces/{namespace}/explain_query:
    post:
      description: Explain a query plan.
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/QueryConfig'
              - $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: The query plan explanation.
          content:
            application/json:
              schema:
                description: The response to a successful query explain.
                type: object
                properties:
                  plan_text:
                    type: string
                    description: The textual representation of the query plan.
        default:
          description: An error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Namespaces
components:
  schemas:
    Limit:
      description: Limits the documents returned by a query.
      type: object
      properties:
        total:
          description: Limits the total number of documents returned.
          type: integer
        per:
          description: 'Limits the number of documents with the same value for a set of attributes (the "limit key") that can appear in the results.

            '
          type: object
          properties:
            attributes:
              description: The attributes to include in the limit key.
              type: array
              items:
                type: string
            limit:
              description: 'The maximum number of documents to return for each value of the limit key.

                '
              type: integer
          required:
          - attributes
          - limit
      required:
      - total
    PatchByFilter:
      description: The patch and filter specifying which documents to patch.
      required:
      - patch
      - filters
      properties:
        patch:
          type: object
          additionalProperties: true
        filters:
          x-stainless-any: true
          description: Filter by attributes. Same syntax as the query endpoint.
    CopyFromNamespaceParams:
      oneOf:
      - type: string
        description: The namespace to copy documents from.
        x-stainless-skip:
        - go
      - $ref: '#/components/schemas/CopyFromNamespaceConfig'
    Tokenizer:
      description: The tokenizer to use for full-text search on an attribute. Defaults to `word_v3`.
      oneOf:
      - const: pre_tokenized_array
      - const: word_v0
      - const: word_v1
      - const: word_v2
      - const: word_v3
    Columns:
      description: 'A list of documents in columnar format. Each key is a column name, mapped to an array of values for that column.

        '
      type: object
      properties:
        id:
          type: array
          description: The IDs of the documents.
          items:
            $ref: '#/components/schemas/Id'
        vector:
          oneOf:
          - type: array
            description: The vector embeddings of the documents.
            items:
              $ref: '#/components/schemas/Vector'
          - $ref: '#/components/schemas/Vector'
      required:
      - id
      additionalProperties:
        type: array
        items:
          x-stainless-any: true
        description: The attributes attached to each of the documents.
    DistanceMetric:
      anyOf:
      - const: cosine_distance
        description: 'Defined as `1 - cosine_similarity` and ranges from 0 to 2. Lower is better.

          '
      - const: euclidean_squared
        description: Defined as `sum((x - y)^2)`. Lower is better.
      description: A function used to calculate vector similarity.
    AttributeSchema:
      description: The schema for an attribute attached to a document.
      anyOf:
      - $ref: '#/components/schemas/AttributeType'
        x-stainless-skip:
        - go
      - $ref: '#/components/schemas/AttributeSchemaConfig'
    Row:
      description: A single document, in a row-based format.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        vector:
          $ref: '#/components/schemas/Vector'
      required:
      - id
      additionalProperties: true
    Query:
      description: Query, filter, full-text search and vector search documents.
      type: object
      properties:
        rank_by:
          description: 'How to rank the documents in the namespace.

            '
          x-stainless-any: true
        top_k:
          description: The number of results to return.
          type: integer
        filters:
          description: 'Exact filters for attributes to refine search results for. Think of it as a SQL WHERE clause.

            '
          x-stainless-any: true
        include_attributes:
          $ref: '#/components/schemas/IncludeAttributes'
        exclude_attributes:
          description: 'List of attribute names to exclude from the response. All other attributes will be included in the response.

            '
          type: array
          items:
            type: string
        aggregate_by:
          description: 'Aggregations to compute over all documents in the namespace that match the filters.

            '
          type: object
          additionalProperties: true
        group_by:
          description: 'Groups documents by the specified attributes (the "group key") before computing aggregates. Aggregates are computed separately for each group.

            '
          type: array
          items:
            x-stainless-any: true
        distance_metric:
          $ref: '#/components/schemas/DistanceMetric'
        limit:
          anyOf:
          - type: integer
            x-stainless-skip:
            - go
          - $ref: '#/components/schemas/Limit'
    NamespaceMetadata:
      description: Metadata about a namespace.
      type: object
      properties:
        schema:
          description: The schema of the namespace.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeSchemaConfig'
        approx_row_count:
          type: integer
          format: int64
          description: The approximate number of rows in the namespace.
        approx_logical_bytes:
          type: integer
          format: int64
          description: The approximate number of logical bytes in the namespace.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the namespace was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the namespace was last modified by a write operation.
        encryption:
          $ref: '#/components/schemas/Encryption'
        index:
          oneOf:
          - type: object
            title: index-up-to-date
            properties:
              status:
                const: up-to-date
            required:
            - status
          - type: object
            title: index-updating
            properties:
              status:
                const: updating
              unindexed_bytes:
                type: integer
                description: The number of bytes in the namespace that are in the write-ahead log but have not yet been indexed.
            required:
            - status
            - unindexed_bytes
        pinning:
          $ref: '#/components/schemas/PinningConfigResponse'
      required:
      - schema
      - approx_logical_bytes
      - approx_row_count
      - created_at
      - updated_at
      - encryption
      - index
    BranchFromNamespaceParams:
      oneOf:
      - type: string
        description: The namespace to create an instant, copy-on-write clone of.
        x-stainless-skip:
        - go
      - $ref: '#/components/schemas/BranchFromNamespaceConfig'
    Vector:
      description: A vector embedding associated with a document.
      oneOf:
      - description: A dense vector encoded as an array of floats.
        type: array
        items:
          type: number
          x-turbopuffer-width: 32
      - description: A dense vector encoded as a base64 string.
        type: string
    AggregationGroup:
      description: A single aggregation group.
      type: object
      additionalProperties: true
    FullTextSearch:
      description: 'Whether this attribute can be used as part of a BM25 full-text search. Requires the `string` or `[]string` type, and by default, BM25-enabled attributes are not filterable. You can override this by setting `filterable: true`.

        '
      oneOf:
      - type: boolean
        x-stainless-skip:
        - go
      - $ref: '#/components/schemas/FullTextSearchConfig'
    IncludeAttributes:
      oneOf:
      - description: 'When `true`, include all attributes in the response. When `false`, include no attributes in the response.

          '
        type: boolean
      - description: 'Include exactly the specified attributes in the response.

          '
        type: array
        items:
          type: string
      description: Whether to include attributes in the response.
    SparseDistanceMetric:
      anyOf:
      - const: dot_product
        description: 'Defined as `sum(x * y)`. Higher is better.

          '
      description: A function used to calculate sparse vector similarity.
    VectorEncoding:
      description: The encoding to use for vectors in the response.
      oneOf:
      - const: float
      - const: base64
    Language:
      description: 'Describes the language of a text attribute. Defaults to `english`.

        '
      oneOf:
      - const: arabic
      - const: danish
      - const: dutch
      - const: english
      - const: finnish
      - const: french
      - const: german
      - const: greek
      - const: hungarian
      - const: italian
      - const: norwegian
      - const: portuguese
      - const: romanian
      - const: russian
      - const: spanish
      - const: swedish
      - const: tamil
      - const: turkish
    Write:
      description: Create, update, or delete documents.
      type: object
      properties:
        upsert_columns:
          $ref: '#/components/schemas/Columns'
        upsert_rows:
          type: array
          items:
            $ref: '#/components/schemas/Row'
        patch_columns:
          $ref: '#/components/schemas/Columns'
        patch_rows:
          type: array
          items:
            $ref: '#/components/schemas/Row'
        deletes:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        upsert_condition:
          description: 'A condition evaluated against the current value of each document targeted by an upsert write. Only documents that pass the condition are upserted.

            '
          x-stainless-any: true
        patch_condition:
          description: 'A condition evaluated against the current value of each document targeted by a patch write. Only documents that pass the condition are patched.

            '
          x-stainless-any: true
        delete_condition:
          description: 'A condition evaluated against the current value of each document targeted by a delete write. Only documents that pass the condition are deleted.

            '
          x-stainless-any: true
        distance_metric:
          $ref: '#/components/schemas/DistanceMetric'
        schema:
          description: 'The schema of the attributes attached to the documents.

            '
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeSchema'
        branch_from_namespace:
          $ref: '#/components/schemas/BranchFromNamespaceParams'
        copy_from_namespace:
          $ref: '#/components/schemas/CopyFromNamespaceParams'
        delete_by_filter:
          description: The filter specifying which documents to delete.
          x-stainless-any: true
        delete_by_filter_allow_partial:
          type: boolean
          description: Allow partial completion when filter matches too many documents.
        patch_by_filter:
          $ref: '#/components/schemas/PatchByFilter'
        patch_by_filter_allow_partial:
          type: boolean
          description: Allow partial completion when filter matches too many documents.
        return_affected_ids:
          type: boolean
          description: 'If true, return the IDs of affected rows (deleted, patched, upserted) in the response. For filtered and conditional writes, only IDs for writes that succeeded will be included.

            '
          default: false
        encryption:
          $ref: '#/components/schemas/Encryption'
        disable_backpressure:
          type: boolean
          description: 'Disables write throttling (HTTP 429 responses) during high-volume ingestion.

            '
    PinningConfigResponse:
      description: 'Configuration for namespace pinning, along with the current status of the pinned namespace.

        '
      allOf:
      - $ref: '#/components/schemas/PinningConfig'
      - type: object
        properties:
          status:
            $ref: '#/components/schemas/PinningStatus'
    Encryption:
      description: The encryption configuration for a namespace.
      oneOf:
      - type: object
        description: Encrypt the namespace with a customer-managed encryption key (CMEK).
        title: customer-managed
        properties:
          mode:
            const: customer-managed
          key_name:
            type: string
            description: 'The identifier of the CMEK key to use for encryption. For GCP, the fully-qualified resource name of the key. For AWS, the ARN of the key.

              '
        required:
        - mode
        - key_name
      - type: object
        description: Use the default server-side encryption (SSE).
        title: default
        properties:
          mode:
            const: default
        required:
        - mode
    Ann:
      description: 'Whether to create an approximate nearest neighbor index for the attribute. Can be a boolean or a detailed configuration object.

        '
      oneOf:
      - type: boolean
        x-stainless-skip:
        - go
      - $ref: '#/components/schemas/AnnConfig'
    QueryResult:
      description: The result of a query.
      type: object
      allOf:
      - $ref: '#/components/schemas/SingleQueryResult'
      - type: object
        properties:
          performance:
            $ref: '#/components/schemas/QueryPerformance'
          billing:
            $ref: '#/components/schemas/QueryBilling'
        required:
        - performance
        - billing
    AttributeType:
      description: 'The data type of the attribute. Valid values: string, int, uint, float, uuid, datetime, bool, []string, []int, []uint, []float, []uuid, []datetime, []bool, [DIMS]f16, [DIMS]f32, {}f16.

        '
      type: string
    ErrorResponse:
      description: The response to an unsuccessful request.
      type: object
      required:
      - status
      - error
      properties:
        status:
          const: error
          description: The status of the request.
        error:
          type: string
          description: The error message.
    NamespaceSummary:
      description: A summary of a namespace.
      type: object
      properties:
        id:
          type: string
          description: The namespace ID.
      required:
      - id
    CopyFromNamespaceConfig:
      type: object
      properties:
        source_namespace:
          type: string
          description: The namespace to copy documents from.
        source_api_key:
          type: string
          description: (Optional) An API key for the organization containing the source namespace
        source_region:
          type: string
          description: (Optional) The region of the source namespace.
      required:
      - source_namespace
    PinningConfig:
      description: Configuration for namespace pinning.
      type: object
      properties:
        replicas:
          type: integer
          format: int64
          minimum: 1
          description: The number of read replicas to provision. Defaults to 1 if not specified.
    QueryPerformance:
      description: The performance information for a query.
      type: object
      properties:
        cache_hit_ratio:
          type: number
          description: The ratio of cache hits to total cache lookups.
        cache_temperature:
          type: string
          description: A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
        server_total_ms:
          type: integer
          description: 'Request time measured on the server, including time spent waiting for other queries to complete if the namespace was at its concurrency limit.

            '
        query_execution_ms:
          type: integer
          description: 'Request time measured on the server, excluding time spent waiting due to the namespace concurrency limit.

            '
        exhaustive_search_count:
          type: integer
          description: The number of unindexed documents processed by the query.
        approx_namespace_size:
          type: integer
          description: the approximate number of documents in the namespace.
      required:
      - cache_hit_ratio
      - cache_temperature
      - server_total_ms
      - query_execution_ms
      - exhaustive_search_count
      - approx_namespace_size
    QueryConfig:
      description: Configuration options for a query.
      type: object
      properties:
        vector_encoding:
          $ref: '#/components/schemas/VectorEncoding'
        consistency:
          description: The consistency level for a query.
          type: object
          properties:
            level:
              anyOf:
              - const: strong
                description: 'Strong consistency. Requires a round-trip to object storage to fetch the latest writes.

                  '
              - const: eventual
                description: 'Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.

                  '
              description: The query's consistency level.
    AnnConfig:
      description: Configuration options for ANN (Approximate Nearest Neighbor) indexing.
      type: object
      properties:
       

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/turbopuffer/refs/heads/main/openapi/turbopuffer-namespaces-api-openapi.yml