> ## 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 captioned images



## OpenAPI

````yaml /openapi.json post /v1/search
openapi: 3.1.0
info:
  title: Lightdrift API
  version: '1.2'
  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:
      summary: Search captioned images
      operationId: search_v1_search_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            default: ''
            title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchReq'
      responses:
        '200':
          description: Search results and source-declared rights.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                query_id: q_33b7214c7da1a07ce4355a40
                results:
                  - asset_id: isorepublic:17191
                    score: 0.921875
                    title: Mini in Brooklyn
                    source: isorepublic
                    ai_generated: false
                    width: 4000
                    height: 2667
                    file: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191
                    thumb: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191?v=thumb
                    rights:
                      license: cc0
                      license_verbatim: CC0 1.0
                      commercial: true
                      attribution_required: false
                      derivatives: true
                      share_alike: false
                      attribution: null
                      provenance_url: https://isorepublic.com/photo/mini-in-brooklyn/
                      basis: as-declared by source; verify for critical use
                  - asset_id: flickr:51141533761
                    score: 0.90234375
                    title: Night in the city-2
                    source: flickr
                    ai_generated: false
                    width: 1023
                    height: 968
                    file: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761
                    thumb: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761?v=thumb
                    rights:
                      license: cc-by-sa
                      license_verbatim: CC BY-SA 2.0
                      commercial: true
                      attribution_required: true
                      derivatives: true
                      share_alike: true
                      attribution: >-
                        "Night in the city-2" by Tatiana El-Bakri, flickr, CC
                        BY-SA
                      provenance_url: https://www.flickr.com/photos/189281045@N03/51141533761
                      basis: as-declared by source; verify for critical use
                  - asset_id: yfcc:9715466326
                    score: 0.85546875
                    title: MINIPalooza 2013
                    source: yfcc
                    ai_generated: false
                    width: 1024
                    height: 575
                    file: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326
                    thumb: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326?v=thumb
                    rights:
                      license: cc-by
                      license_verbatim: by <>
                      commercial: true
                      attribution_required: true
                      derivatives: true
                      share_alike: false
                      attribution: '"MINIPalooza 2013" by unknown, yfcc, CC BY 4.0/3.0/2.0'
                      provenance_url: http://www.flickr.com/photos/101530550@N05/9715466326/
                      basis: as-declared by source; verify for critical use
                  - asset_id: yfcc:9958535786
                    score: 0.85546875
                    title: Study in Blue - Phibsboro [Dublin] - 89 Phibsborough Road
                    source: yfcc
                    ai_generated: false
                    width: 1023
                    height: 697
                    file: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786
                    thumb: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786?v=thumb
                    rights:
                      license: cc-by-sa
                      license_verbatim: by-sa <>
                      commercial: true
                      attribution_required: true
                      derivatives: true
                      share_alike: true
                      attribution: >-
                        "Study in Blue - Phibsboro [Dublin] - 89 Phibsborough
                        Road" by unknown, yfcc, CC BY-SA
                      provenance_url: http://www.flickr.com/photos/80824546@N00/9958535786/
                      basis: as-declared by source; verify for critical use
                  - asset_id: wm_quality:194126027
                    score: 0.8359375
                    title: AC BD Lochnerstraße 21.jpg
                    source: wm_quality
                    ai_generated: false
                    width: 2581
                    height: 3226
                    file: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027
                    thumb: >-
                      https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027?v=thumb
                    rights:
                      license: cc-by-sa
                      license_verbatim: CC BY-SA 4.0
                      commercial: true
                      attribution_required: true
                      derivatives: true
                      share_alike: true
                      attribution: >-
                        "AC BD Lochnerstraße 21.jpg" by Grunpfnul, wm_quality,
                        CC BY-SA
                      provenance_url: >-
                        https://commons.wikimedia.org/wiki/File:AC_BD_Lochnerstra%C3%9Fe_21.jpg
                      basis: as-declared by source; verify for critical use
                latency_ms: 439
                timing_ms:
                  embed: 180
                  retrieve: 70
                  rerank: 161
                mode: text
                ranking: text
                pool_size: 131
                reranked: 60
                backend: voyage
          headers:
            X-RateLimit-Limit:
              schema:
                type: string
              description: e.g. `60/min, 5000/day`
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the tighter window
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the minute window resets
            X-RateLimit-Tier:
              schema:
                type: string
                enum:
                  - promo
                  - starter
                  - growth
                  - scale
                  - enterprise
            X-Concurrency-Limit:
              schema:
                type: integer
              description: Searches allowed in flight at once
        '402':
          description: Insufficient prepaid credit.
          content:
            application/json:
              example:
                detail: insufficient credit
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit or concurrency limit exceeded; `Retry-After` in seconds.
          headers:
            Retry-After:
              schema:
                type: integer
            X-RateLimit-Limit:
              schema:
                type: string
              description: e.g. `60/min, 5000/day`
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the tighter window
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the minute window resets
            X-RateLimit-Tier:
              schema:
                type: string
                enum:
                  - promo
                  - starter
                  - growth
                  - scale
                  - enterprise
            X-Concurrency-Limit:
              schema:
                type: integer
              description: Searches allowed in flight at once
          content:
            application/json:
              examples:
                rate:
                  value:
                    detail: 'rate limit exceeded: 30 per minute on the promo tier'
                concurrency:
                  value:
                    detail: too many concurrent requests for this account (max 2)
        '503':
          description: >-
            Search/provider/auth dependency unavailable. Honor Retry-After;
            failed search is not charged.
components:
  schemas:
    SearchReq:
      properties:
        query:
          type: string
          title: Query
        k:
          type: integer
          maximum: 100
          minimum: 1
          title: K
          default: 10
        ann_k:
          type: integer
          maximum: 1000
          minimum: 1
          title: Ann K
          default: 100
        bm25_k:
          type: integer
          maximum: 1000
          minimum: 0
          title: Bm25 K
          default: 50
        ann_ef:
          type: integer
          maximum: 4096
          minimum: 64
          title: Ann Ef
          default: 2048
        mode:
          type: string
          enum:
            - auto
            - none
            - text
          title: Mode
          default: auto
        rerank:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Rerank
        rerank_k:
          anyOf:
            - type: integer
              maximum: 500
              minimum: 1
            - type: 'null'
          title: Rerank K
          default: 60
        rerank_text:
          type: boolean
          title: Rerank Text
          default: true
        explain:
          type: boolean
          title: Explain
          default: false
        filters:
          $ref: '#/components/schemas/Filters'
        include_graphics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Include Graphics
        client_session:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Session
        experiment:
          anyOf:
            - type: string
            - type: 'null'
          title: Experiment
      type: object
      required:
        - query
      title: SearchReq
    SearchResponse:
      type: object
      properties:
        query_id:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
        latency_ms:
          type: integer
        timing_ms:
          type: object
          properties:
            embed:
              type: integer
            retrieve:
              type: integer
            rerank:
              type: integer
        mode:
          type: string
        ranking:
          type: string
          description: Actual ordering, including text, visual, none, or none (degraded).
        pool_size:
          type: integer
        reranked:
          type: integer
        backend:
          type: string
          description: >-
            Voyage responses report voyage; legacy responses may omit this
            field.
        degraded:
          type: string
          description: >-
            Reranker unavailable; results are in retrieval order. Successful
            billed response.
        relaxed:
          type: array
          items:
            type: string
          description: >-
            Default filters relaxed to fill results; explicit constraints are
            not relaxed.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Filters:
      properties:
        commercial:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Commercial
        attribution_required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Attribution Required
        derivatives:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Derivatives
        license_id:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: License Id
        source:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source
        min_width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Min Width
        min_height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Min Height
        orientation:
          anyOf:
            - type: string
            - type: 'null'
          title: Orientation
        colors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Colors
        monochrome:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Monochrome
        year_min:
          anyOf:
            - type: integer
            - type: 'null'
          title: Year Min
        year_max:
          anyOf:
            - type: integer
            - type: 'null'
          title: Year Max
        ai_generated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Ai Generated
        nsfw_max:
          anyOf:
            - type: number
            - type: 'null'
          title: Nsfw Max
          default: 0.2
        format:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Format
      type: object
      title: Filters
    Result:
      type: object
      properties:
        asset_id:
          type: string
        score:
          type:
            - number
            - 'null'
        title:
          type: string
        source:
          type: string
        ai_generated:
          type: boolean
        width:
          type: integer
        height:
          type: integer
        file:
          type: string
        thumb:
          type: string
        rights:
          $ref: '#/components/schemas/Rights'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    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
            - 'null'
        provenance_url:
          type: string
        basis:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Lightdrift API key. Usage is metered per query.

````