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

# Promote a field

> Promotes a field to a fast, indexed field so it can be used efficiently in filters and aggregations. Requires an admin role.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/admin/fields/promote
openapi: 3.1.0
info:
  description: >-
    Splendor is a search and retrieval API for your operational data. Ingest

    datasets — logs, documents, and structured records — and query them through
    one

    consistent interface that spans full-text, SQL, and semantic (vector)
    search.


    Every request authenticates with a bearer token and selects a workspace with
    the

    `X-Splendor-Tenant-Id` header. Read and query operations are available to
    any

    member; operations that create, change, or delete data require an admin
    role.


    All search modes return one shared envelope, and every result carries
    provenance

    back to the exact source object it came from.
  title: Splendor API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.withsplendor.com
security:
  - bearerAuth: []
tags:
  - description: Resolve the authenticated user and the tenants they can access.
    name: Identity
  - description: >-
      Build on Splendor as a platform: authenticate with a platform API key to
      provision an isolated tenant per end-customer and manage your platform
      keys.
    name: Platform
  - description: >-
      List datasets, inspect inferred schemas and readiness, and manage dataset
      lifecycle including deletion and schema rebuilds.
    name: Datasets & schema
  - description: >-
      Run full-text, SQL, and semantic search over your datasets, stream
      results, and resolve object media.
    name: Search & query
  - description: Save queries and materialize result sets for repeatable analysis.
    name: Views
  - description: >-
      Define named, versioned, parameterized SQL queries and manage their
      versions.
    name: Query Endpoints
  - description: Create and manage asynchronous exports of search results.
    name: Exports
  - description: >-
      Configure data sources, upload data through hosted multipart uploads,
      stream logs, and track ingest runs.
    name: Sources & ingest
  - description: >-
      Connect third-party systems by managing connector instances in the
      selected tenant.
    name: Connectors
  - description: Define and test detection rules that run against incoming data.
    name: Detections
  - description: Inspect discovered fields and promote them to fast, aggregatable fields.
    name: Fields
  - description: >-
      Operational visibility and recovery: audit logs, usage, dead-letter queue,
      reindex jobs, and data-deletion jobs.
    name: Operations
paths:
  /v1/admin/fields/promote:
    post:
      tags:
        - Fields
      summary: Promote a field
      description: >-
        Promotes a field to a fast, indexed field so it can be used efficiently
        in filters and aggregations. Requires an admin role.
      operationId: promoteField
      parameters:
        - $ref: '#/components/parameters/SplendorTenantId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldPromotionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldPromotionResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request is invalid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The requested resource was not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  parameters:
    SplendorTenantId:
      description: Selects the tenant (workspace) the request acts within.
      in: header
      name: x-splendor-tenant-id
      required: true
      schema:
        type: string
  schemas:
    FieldPromotionRequest:
      properties:
        dataset_id:
          title: Dataset Id
          type: string
        field_path:
          minLength: 1
          title: Field Path
          type: string
        tenant_id:
          title: Tenant Id
          type: string
        value_type:
          anyOf:
            - enum:
                - text
                - keyword
                - i64
                - f64
                - datetime
                - bool
                - ip
              type: string
            - type: 'null'
          title: Value Type
      required:
        - tenant_id
        - dataset_id
        - field_path
      title: FieldPromotionRequest
      type: object
    FieldPromotionResponse:
      example:
        field:
          dataset_id: app-logs
          fast: true
          field_path: latency_ms
          indexed: true
          seen_count: 1240000
          stored: true
          tenant_id: acme
          type: i64
          variants:
            - dataset_id: app-logs
              fast: true
              field_path: latency_ms
              indexed: true
              physical_field: latency_ms_i64
              sample_value: '42'
              seen_count: 1240000
              stored: true
              tenant_id: acme
              value_type: i64
        index_id: acme__app-logs
        index_response: {}
        promotion_id: prom_1
        reindex_required: true
        status: reindex_required
        target_generation_id: 5
      properties:
        field:
          $ref: '#/components/schemas/FieldRegistryItem'
        index_id:
          title: Index Id
          type: string
        index_response:
          additionalProperties: true
          title: Index Response
          type: object
        promotion_id:
          title: Promotion Id
          type: string
        reindex_required:
          title: Reindex Required
          type: boolean
        status:
          title: Status
          type: string
        target_generation_id:
          title: Target Generation Id
          type: integer
      required:
        - field
        - index_id
        - promotion_id
        - target_generation_id
        - status
        - reindex_required
        - index_response
      title: FieldPromotionResponse
      type: object
    ApiError:
      description: >-
        Error envelope returned by every Splendor API endpoint.


        ``detail`` is either a plain message string (most errors) or a
        structured

        ``{code, message}`` object (validation and capacity errors that carry a
        stable

        machine-readable code).
      examples:
        - detail: Dataset not found
        - detail:
            code: semantic_search_capacity_exhausted
            message: Semantic search capacity is temporarily exhausted; retry shortly.
      properties:
        detail:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/ErrorBody'
          title: Detail
      required:
        - detail
      title: ApiError
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    FieldRegistryItem:
      properties:
        dataset_id:
          title: Dataset Id
          type: string
        fast:
          title: Fast
          type: boolean
        field_path:
          title: Field Path
          type: string
        indexed:
          title: Indexed
          type: boolean
        seen_count:
          title: Seen Count
          type: integer
        stored:
          title: Stored
          type: boolean
        tenant_id:
          title: Tenant Id
          type: string
        type:
          title: Type
          type: string
        variants:
          items:
            $ref: '#/components/schemas/FieldRegistryVariantItem'
          title: Variants
          type: array
      required:
        - tenant_id
        - dataset_id
        - field_path
        - type
        - indexed
        - fast
        - stored
        - seen_count
      title: FieldRegistryItem
      type: object
    ErrorBody:
      description: Structured error detail returned by validation and capacity errors.
      examples:
        - code: semantic_query_text_required
          message: Semantic vector search requires non-empty text.
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: ErrorBody
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    FieldRegistryVariantItem:
      properties:
        dataset_id:
          title: Dataset Id
          type: string
        fast:
          title: Fast
          type: boolean
        field_path:
          title: Field Path
          type: string
        indexed:
          title: Indexed
          type: boolean
        physical_field:
          title: Physical Field
          type: string
        sample_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Sample Value
        seen_count:
          title: Seen Count
          type: integer
        stored:
          title: Stored
          type: boolean
        tenant_id:
          title: Tenant Id
          type: string
        value_type:
          title: Value Type
          type: string
      required:
        - tenant_id
        - dataset_id
        - field_path
        - value_type
        - physical_field
        - indexed
        - fast
        - stored
        - seen_count
        - sample_value
      title: FieldRegistryVariantItem
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
      description: The bearer token is missing, malformed, or expired.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
      description: The token lacks access to the tenant or the role required.
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: API token issued from the Splendor console.
      scheme: bearer
      type: http

````