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

# Search

> Text query over the corpus, with optional design-layer filters and a negative constraint. Returns ranked results, each with a machine-readable rights answer.



## OpenAPI

````yaml /openapi.json post /v1/search
openapi: 3.1.0
info:
  title: Lightdrift API
  version: 0.1.0
  description: >-
    Natural-language image search for agents. Describe what you want — in text,
    with a reference image, or both — and get ranked images back, each with a
    machine-readable rights answer. Retrieval only: no generation, no checkout.
servers:
  - url: https://api.lightdrift.ai
    description: Production
security:
  - apiKey: []
paths:
  /v1/search:
    post:
      tags:
        - Search
      summary: Search
      description: >-
        Text query over the corpus, with optional design-layer filters and a
        negative constraint. Returns ranked results, each with a
        machine-readable rights answer.
      operationId: search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: a spanish shawl nudibranch on a reef
              negative: divers
              k: 8
      responses:
        '200':
          description: Ranked results with rights.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                query: a spanish shawl nudibranch on a reef
                count: 1
                latency_ms: 96
                results:
                  - asset_id: inat:41290763
                    score: 0.83214
                    title: Spanish shawl (Flabellina iodinea)
                    file: https://assets.lightdrift.ai/inat/41290763.jpg
                    license: cc-by-4.0
                    rights:
                      license: cc-by-4.0
                      license_version: '4.0'
                      license_url: https://creativecommons.org/licenses/by/4.0/
                      as_declared_by: iNaturalist
                      commercial: true
                      derivatives: true
                      share_alike: false
                      attribution_required: true
                      ai_training: null
                      delivery: host
                      attribution: >-
                        "Spanish shawl (Flabellina iodinea)" by anudibranchmom,
                        iNaturalist, CC BY 4.0
                      provenance: iNaturalist research-grade observations
                      note: null
                      basis: >-
                        Rights shown as declared by the source, not verified by
                        Lightdrift.
                    cv:
                      palette:
                        - '#5a2d82'
                        - '#f26d3d'
                        - '#1b3a4d'
                      luminance: 0.31
                      neg_space:
                        - top
                      faces: 0
                      aspect: 1.5
        '500':
          description: Search failed.
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Natural-language description of what you need.
        k:
          type: integer
          default: 10
          maximum: 100
        ann_k:
          type: integer
          default: 100
          maximum: 1000
          description: Vector-lane candidate depth. Raise for vibe/aesthetic queries.
        bm25_k:
          type: integer
          default: 50
          maximum: 1000
          description: Keyword-lane candidate depth. Raise for precise subjects and names.
        filters:
          $ref: '#/components/schemas/Filters'
        client_session:
          type: string
          description: >-
            Optional session id; link related queries for better results over
            time.
        experiment:
          type: string
    SearchResponse:
      type: object
      properties:
        query:
          type: string
        count:
          type: integer
        latency_ms:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
        applied_design:
          type:
            - object
            - 'null'
          description: >-
            Present when `parse_design` was set: the filters inferred from the
            query text and the phrases that matched.
    Filters:
      type: object
      description: All filters are hard constraints applied before ranking.
      properties:
        commercial:
          type: boolean
        attribution_required:
          type: boolean
        derivatives:
          type: boolean
        license_id:
          type: array
          items:
            type: string
        source:
          type: array
          items:
            type: string
        min_width:
          type: integer
        min_height:
          type: integer
        orientation:
          type: string
          enum:
            - landscape
            - portrait
            - square
        colors:
          type: array
          items:
            type: string
        monochrome:
          type: boolean
        year_min:
          type: integer
        year_max:
          type: integer
        ai_generated:
          type: boolean
        nsfw_max:
          type: number
          default: 0.2
        format:
          type: array
          items:
            type: string
    Result:
      type: object
      properties:
        asset_id:
          type: string
        score:
          type: number
        title:
          type: string
        source:
          type: string
        width:
          type: integer
        height:
          type: integer
        file:
          type: string
          description: Tracked URL redirecting to the full-resolution file.
        thumb:
          type: string
        rights:
          $ref: '#/components/schemas/Rights'
    Rights:
      type: object
      properties:
        license:
          type: string
        license_verbatim:
          type: string
        commercial:
          type: boolean
        attribution_required:
          type: boolean
        derivatives:
          type: boolean
        share_alike:
          type: boolean
        attribution:
          type: string
          nullable: true
          description: Ready-to-use attribution string; null when not required.
        provenance_url:
          type: string
        basis:
          type: string
          description: as-declared by source; verify for critical use
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Lightdrift API key. Usage is metered per query.

````