> ## 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.

# Create a view

> Creates a view from exactly one source: an existing `from_search_id` handle or a full `search_request`. A view is either materialized (membership and rank frozen at creation) or live (the query re-runs on read). Use materialized views for deterministic, repeatable analysis.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/views
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/views:
    post:
      tags:
        - Views
      summary: Create a view
      description: >-
        Creates a view from exactly one source: an existing `from_search_id`
        handle or a full `search_request`. A view is either materialized
        (membership and rank frozen at creation) or live (the query re-runs on
        read). Use materialized views for deterministic, repeatable analysis.
      operationId: createView
      parameters:
        - $ref: '#/components/parameters/SplendorTenantId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewResponse'
          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'
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The search handle, cursor, or view has expired.
        '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:
    ViewCreateRequest:
      properties:
        from_search_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: From Search Id
        name:
          anyOf:
            - maxLength: 255
              minLength: 1
              type: string
            - type: 'null'
          title: Name
        search_request:
          anyOf:
            - $ref: '#/components/schemas/SearchRequest'
            - type: 'null'
      title: ViewCreateRequest
      type: object
    ViewResponse:
      additionalProperties: true
      example:
        created_at: '2026-01-15T09:30:00Z'
        expires_at: '2026-01-15T09:30:00Z'
        from_search_id: srch_8f2c
        kind: materialized
        name: Timeout errors
        record_count: 1240
        total:
          relation: eq
          value: 1240
        view_id: view_01H8Z3
      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
    SearchRequest:
      example:
        aggregations: []
        collapse: null
        content_filter: text
        cursor: null
        dataset_scope: selected
        datasets:
          - app-logs
        limit: 20
        max_expansion_terms: 10
        q: null
        semantic: false
        semantic_min_score: null
        text: timeout
        time: null
        where: []
      properties:
        aggregations:
          items:
            $ref: '#/components/schemas/AggregationRequest'
          title: Aggregations
          type: array
        collapse:
          anyOf:
            - enum:
                - document
                - record
              type: string
            - type: 'null'
          description: >-
            Override how lexical hits map to results. 'document' returns the
            best-ranked record per document (use to force a document listing
            from a filter-only browse); 'record' returns every matching record
            (use with a document filter to enumerate each instance of a term
            within one document). Defaults to document collapse for ranked text
            and record semantics for filter-only browses. Not valid with
            semantic search, which always returns document-level results.
          title: Collapse
        content_filter:
          default: text
          description: >-
            For semantic search, which modalities to retrieve: 'text' (default)
            searches text/document embeddings; 'images' searches image
            embeddings via SigLIP; 'all' searches both and merges the results.
          enum:
            - all
            - text
            - images
          title: Content Filter
          type: string
        cursor:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: Cursor
        dataset_scope:
          default: selected
          enum:
            - selected
            - all
          title: Dataset Scope
          type: string
        datasets:
          items:
            type: string
          title: Datasets
          type: array
        limit:
          default: 20
          maximum: 1000
          minimum: 0
          title: Limit
          type: integer
        max_expansion_terms:
          default: 10
          maximum: 50
          minimum: 1
          title: Max Expansion Terms
          type: integer
        q:
          anyOf:
            - type: string
            - type: 'null'
          title: Q
        semantic:
          default: false
          title: Semantic
          type: boolean
        semantic_min_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Semantic Min Score
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
        time:
          anyOf:
            - $ref: '#/components/schemas/TimeRange'
            - type: 'null'
        where:
          items:
            $ref: '#/components/schemas/StructuredFilter'
          title: Where
          type: array
      title: SearchRequest
      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
    AggregationRequest:
      properties:
        field:
          minLength: 1
          title: Field
          type: string
        interval:
          anyOf:
            - type: string
            - type: 'null'
          title: Interval
        name:
          minLength: 1
          title: Name
          type: string
        percents:
          items:
            type: number
          title: Percents
          type: array
        size:
          default: 10
          maximum: 1000
          minimum: 1
          title: Size
          type: integer
        type:
          enum:
            - terms
            - date_histogram
            - stats
            - percentiles
            - value_count
          title: Type
          type: string
        value_type:
          anyOf:
            - enum:
                - text
                - keyword
                - i64
                - f64
                - datetime
                - bool
                - ip
              type: string
            - type: 'null'
          title: Value Type
      required:
        - name
        - type
        - field
      title: AggregationRequest
      type: object
    TimeRange:
      properties:
        gt:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Gt
        gte:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Gte
        lt:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Lt
        lte:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Lte
      title: TimeRange
      type: object
    StructuredFilter:
      properties:
        field:
          title: Field
          type: string
        op:
          enum:
            - eq
            - in
            - prefix
            - gt
            - gte
            - lt
            - lte
          title: Op
          type: string
        value:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - items:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
              type: array
          title: Value
        value_type:
          anyOf:
            - enum:
                - text
                - keyword
                - i64
                - f64
                - datetime
                - bool
                - ip
              type: string
            - type: 'null'
          title: Value Type
      required:
        - field
        - op
        - value
      title: StructuredFilter
      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

````