{
  "openapi": "3.1.0",
  "info": {
    "title": "Lightdrift API",
    "version": "1.3",
    "description": "Natural-language image search for agents. Describe what you want \u2014 in text, with a reference image, or both \u2014 and get ranked images back, each with a machine-readable rights answer. Retrieval only: no generation, no checkout."
  },
  "paths": {
    "/v1/search": {
      "post": {
        "summary": "Search captioned images",
        "description": "Search captioned images by a natural-language query, a reference image, or both, with optional filters. Returns ranked results where each result carries a machine-readable rights object (source, license, attribution, dimensions) and file URLs, so an agent can decide what it may publish without guessing. Search by image and image plus text require a paid plan. Each search uses 1 credit per 10 results, rounded up, minimum 1; on the Free plan k is capped to 10 and the response carries a notice.",
        "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\u00dfe 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\u00dfe 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",
                  "credits": {
                    "charged": 1,
                    "remaining": 499,
                    "plan": "starter"
                  }
                }
              }
            },
            "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": [
                    "free",
                    "starter",
                    "pro",
                    "scale",
                    "custom"
                  ]
                },
                "description": "The plan id for the request"
              },
              "X-Concurrency-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Searches allowed in flight at once"
              }
            }
          },
          "402": {
            "description": "The plan's monthly credits are used up. Free, Starter and Pro: upgrade to the next plan or wait for the monthly reset. Scale and Custom: buy a credit pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsExhaustedError"
                },
                "examples": {
                  "upgrade": {
                    "summary": "Free, Starter or Pro",
                    "value": {
                      "detail": {
                        "error": "credits_exhausted",
                        "plan": "starter",
                        "message": "You have used all 5,000 credits on the Starter plan this month. Upgrade to Pro or wait for your monthly reset: https://lightdrift.ai/dashboard/billing",
                        "upgrade_url": "https://lightdrift.ai/dashboard/billing",
                        "next_plan": "pro"
                      }
                    }
                  },
                  "credit_pack": {
                    "summary": "Scale or Custom",
                    "value": {
                      "detail": {
                        "error": "credits_exhausted",
                        "plan": "scale",
                        "message": "You have used all 75,000 credits on the Scale plan this month. Buy a 10,000-credit pack for $40 or wait for your monthly reset: https://lightdrift.ai/dashboard/billing",
                        "upgrade_url": "https://lightdrift.ai/dashboard/billing",
                        "next_plan": null,
                        "buy_credits_url": "https://lightdrift.ai/dashboard/billing"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Search by image or image plus text on the Free plan. These features require a paid plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaidFeatureError"
                },
                "example": {
                  "detail": {
                    "error": "paid_feature",
                    "feature": "image_search",
                    "plan": "free",
                    "message": "Search by image, image plus text, and find-similar are available on paid plans (from $29/month). Upgrade: https://lightdrift.ai/dashboard/billing",
                    "upgrade_url": "https://lightdrift.ai/dashboard/billing"
                  }
                }
              }
            }
          },
          "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": [
                    "free",
                    "starter",
                    "pro",
                    "scale",
                    "custom"
                  ]
                },
                "description": "The plan id for the request"
              },
              "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 free plan"
                    }
                  },
                  "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."
          }
        }
      }
    },
    "/v1/similar": {
      "post": {
        "summary": "Find similar indexed images",
        "description": "Find indexed images visually similar to an existing asset_id returned by a previous search. Returns ranked candidates with the same machine-readable rights object as /v1/search. The seed must already be an indexed asset ID, not a newly uploaded image. Requires a paid plan. Uses 1 credit per 10 results, rounded up, minimum 1.",
        "operationId": "similar_v1_similar_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/SimilarReq"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results and source-declared rights.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "query_id": "q_db7b4305df746986bd859ae0",
                  "results": [
                    {
                      "asset_id": "stocksnap:BAVURMUHRD",
                      "score": 0.74583352,
                      "title": "car auto",
                      "source": "stocksnap",
                      "ai_generated": false,
                      "width": 5000,
                      "height": 4000,
                      "file": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:BAVURMUHRD",
                      "thumb": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:BAVURMUHRD?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://stocksnap.io/photo/car-auto-BAVURMUHRD",
                        "basis": "as-declared by source; verify for critical use"
                      }
                    },
                    {
                      "asset_id": "stocksnap:77BA6D52D0",
                      "score": 0.7300238,
                      "title": "red car",
                      "source": "stocksnap",
                      "ai_generated": false,
                      "width": 5035,
                      "height": 3339,
                      "file": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:77BA6D52D0",
                      "thumb": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:77BA6D52D0?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://stocksnap.io/photo/red-car-77BA6D52D0",
                        "basis": "as-declared by source; verify for critical use"
                      }
                    },
                    {
                      "asset_id": "wm_quality:153180537",
                      "score": 0.71327692,
                      "title": "2024 Mi\u0119dzylesie, ul. Wary\u0144skiego 11.jpg",
                      "source": "wm_quality",
                      "ai_generated": false,
                      "width": 3222,
                      "height": 2838,
                      "file": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/wm_quality:153180537",
                      "thumb": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/wm_quality:153180537?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": "\"2024 Mi\u0119dzylesie, ul. Wary\u0144skiego 11.jpg\" by Jacek Halicki, wm_quality, CC BY-SA",
                        "provenance_url": "https://commons.wikimedia.org/wiki/File:2024_Mi%C4%99dzylesie,_ul._Wary%C5%84skiego_11.jpg",
                        "basis": "as-declared by source; verify for critical use"
                      }
                    },
                    {
                      "asset_id": "stocksnap:UOYLKV7K27",
                      "score": 0.69847137,
                      "title": "car auto",
                      "source": "stocksnap",
                      "ai_generated": false,
                      "width": 4898,
                      "height": 3265,
                      "file": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:UOYLKV7K27",
                      "thumb": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/stocksnap:UOYLKV7K27?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://stocksnap.io/photo/car-auto-UOYLKV7K27",
                        "basis": "as-declared by source; verify for critical use"
                      }
                    },
                    {
                      "asset_id": "wm_quality:75913777",
                      "score": 0.69786596,
                      "title": "2001 Rover Mini Cooper Sport 1.3 Rear.jpg",
                      "source": "wm_quality",
                      "ai_generated": false,
                      "width": 3840,
                      "height": 2479,
                      "file": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/wm_quality:75913777",
                      "thumb": "https://api.lightdrift.ai/v1/asset/q_db7b4305df746986bd859ae0/wm_quality:75913777?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": "\"2001 Rover Mini Cooper Sport 1.3 Rear.jpg\" by Vauxford, wm_quality, CC BY-SA",
                        "provenance_url": "https://commons.wikimedia.org/wiki/File:2001_Rover_Mini_Cooper_Sport_1.3_Rear.jpg",
                        "basis": "as-declared by source; verify for critical use"
                      }
                    }
                  ],
                  "latency_ms": 72,
                  "timing_ms": {
                    "retrieve": 72
                  },
                  "ranking": "none",
                  "mode": "none",
                  "pool_size": 99,
                  "reranked": 0,
                  "backend": "voyage",
                  "credits": {
                    "charged": 1,
                    "remaining": 499,
                    "plan": "starter"
                  }
                }
              }
            },
            "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": [
                    "free",
                    "starter",
                    "pro",
                    "scale",
                    "custom"
                  ]
                },
                "description": "The plan id for the request"
              },
              "X-Concurrency-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Searches allowed in flight at once"
              }
            }
          },
          "402": {
            "description": "The plan's monthly credits are used up. Free, Starter and Pro: upgrade to the next plan or wait for the monthly reset. Scale and Custom: buy a credit pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsExhaustedError"
                },
                "examples": {
                  "upgrade": {
                    "summary": "Free, Starter or Pro",
                    "value": {
                      "detail": {
                        "error": "credits_exhausted",
                        "plan": "starter",
                        "message": "You have used all 5,000 credits on the Starter plan this month. Upgrade to Pro or wait for your monthly reset: https://lightdrift.ai/dashboard/billing",
                        "upgrade_url": "https://lightdrift.ai/dashboard/billing",
                        "next_plan": "pro"
                      }
                    }
                  },
                  "credit_pack": {
                    "summary": "Scale or Custom",
                    "value": {
                      "detail": {
                        "error": "credits_exhausted",
                        "plan": "scale",
                        "message": "You have used all 75,000 credits on the Scale plan this month. Buy a 10,000-credit pack for $40 or wait for your monthly reset: https://lightdrift.ai/dashboard/billing",
                        "upgrade_url": "https://lightdrift.ai/dashboard/billing",
                        "next_plan": null,
                        "buy_credits_url": "https://lightdrift.ai/dashboard/billing"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Find similar on the Free plan. This feature requires a paid plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaidFeatureError"
                },
                "example": {
                  "detail": {
                    "error": "paid_feature",
                    "feature": "similar_search",
                    "plan": "free",
                    "message": "Search by image, image plus text, and find-similar are available on paid plans (from $29/month). Upgrade: https://lightdrift.ai/dashboard/billing",
                    "upgrade_url": "https://lightdrift.ai/dashboard/billing"
                  }
                }
              }
            }
          },
          "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": [
                    "free",
                    "starter",
                    "pro",
                    "scale",
                    "custom"
                  ]
                },
                "description": "The plan id for the request"
              },
              "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 free plan"
                    }
                  },
                  "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."
          }
        }
      }
    },
    "/v1/asset/{asset_id}": {
      "get": {
        "summary": "Asset Meta",
        "description": "Return canonical metadata and file URLs for one indexed asset by its asset_id, including the structured rights object and available dimensions and formats. Delivery is separate from search, and returned URLs include the query ID so downloads can be attributed to their search.",
        "operationId": "asset_meta_v1_asset__asset_id__get",
        "parameters": [
          {
            "name": "asset_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Asset Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Asset metadata and file links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetResponse"
                },
                "example": {
                  "asset_id": "isorepublic:17191",
                  "title": "Mini in Brooklyn",
                  "source": "isorepublic",
                  "width": 4000,
                  "height": 2667,
                  "format": "jpeg",
                  "file": "https://api.lightdrift.ai/v1/asset/direct/isorepublic:17191",
                  "thumb": "https://api.lightdrift.ai/v1/asset/direct/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"
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "summary": "Health",
        "description": "Reports the serving configuration. deep=true checks database and Voyage index connectivity; use an actual search to verify provider availability.",
        "operationId": "health_v1_health_get",
        "parameters": [
          {
            "name": "deep",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false,
              "title": "Deep"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/v1/warm": {
      "get": {
        "summary": "Warm",
        "operationId": "warm_v1_warm_get",
        "parameters": [
          {
            "name": "force",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false,
              "title": "Force"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "description": "Default Voyage photo search needs no legacy GPU warm-up. Readiness reflects configuration and recent provider activity, not a guarantee of a successful request."
      }
    },
    "/v1/pricing": {
      "get": {
        "summary": "Plans and credit rules",
        "description": "Return the public plans, monthly credits, per-plan features and limits, the credit counting rule, and the credit pack offer. No API key required.",
        "operationId": "public_pricing",
        "security": [],
        "responses": {
          "200": {
            "description": "Plans, credit rules and the credit pack offer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "results_per_credit": {
                          "type": "integer"
                        },
                        "minimum_per_search": {
                          "type": "integer"
                        },
                        "asset_lookup_credits": {
                          "type": "integer"
                        },
                        "reset": {
                          "type": "string"
                        }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "free",
                              "starter",
                              "pro",
                              "scale",
                              "custom"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "monthly_usd": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Null for Custom (contact us)."
                          },
                          "annual_usd": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Null when the plan has no annual price."
                          },
                          "monthly_credits": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "description": "Null for Custom."
                          },
                          "image_search": {
                            "type": "boolean"
                          },
                          "similar_search": {
                            "type": "boolean"
                          },
                          "max_results": {
                            "type": "integer"
                          },
                          "limits": {
                            "type": "object",
                            "properties": {
                              "rpm": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "rpd": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "concurrent": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          },
                          "support": {
                            "type": "string"
                          },
                          "credit_packs": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "credit_pack": {
                      "type": "object",
                      "properties": {
                        "credits": {
                          "type": "integer"
                        },
                        "usd": {
                          "type": "number"
                        },
                        "plans": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "version": "2026-09-28",
                  "currency": "USD",
                  "credits": {
                    "results_per_credit": 10,
                    "minimum_per_search": 1,
                    "asset_lookup_credits": 0,
                    "reset": "monthly on your billing date; unused credits do not roll over"
                  },
                  "plans": [
                    {
                      "id": "free",
                      "name": "Free",
                      "monthly_usd": 0,
                      "annual_usd": null,
                      "monthly_credits": 500,
                      "image_search": false,
                      "similar_search": false,
                      "max_results": 10,
                      "limits": {
                        "rpm": 30,
                        "rpd": 1000,
                        "concurrent": 2
                      },
                      "support": "Docs",
                      "credit_packs": false
                    },
                    {
                      "id": "starter",
                      "name": "Starter",
                      "monthly_usd": 29,
                      "annual_usd": 290,
                      "monthly_credits": 5000,
                      "image_search": true,
                      "similar_search": true,
                      "max_results": 100,
                      "limits": {
                        "rpm": 60,
                        "rpd": 5000,
                        "concurrent": 4
                      },
                      "support": "Email",
                      "credit_packs": false
                    },
                    {
                      "id": "pro",
                      "name": "Pro",
                      "monthly_usd": 99,
                      "annual_usd": 990,
                      "monthly_credits": 20000,
                      "image_search": true,
                      "similar_search": true,
                      "max_results": 100,
                      "limits": {
                        "rpm": 300,
                        "rpd": 25000,
                        "concurrent": 10
                      },
                      "support": "Priority email",
                      "credit_packs": false
                    },
                    {
                      "id": "scale",
                      "name": "Scale",
                      "monthly_usd": 299,
                      "annual_usd": 2990,
                      "monthly_credits": 75000,
                      "image_search": true,
                      "similar_search": true,
                      "max_results": 100,
                      "limits": {
                        "rpm": 1000,
                        "rpd": 100000,
                        "concurrent": 25
                      },
                      "support": "Shared Slack channel",
                      "credit_packs": true
                    },
                    {
                      "id": "custom",
                      "name": "Custom",
                      "monthly_usd": null,
                      "annual_usd": null,
                      "monthly_credits": null,
                      "image_search": true,
                      "similar_search": true,
                      "max_results": 100,
                      "limits": {
                        "rpm": null,
                        "rpd": null,
                        "concurrent": null
                      },
                      "support": "Dedicated support and SLA",
                      "credit_packs": true
                    }
                  ],
                  "credit_pack": {
                    "credits": 10000,
                    "usd": 40,
                    "plans": [
                      "scale",
                      "custom"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "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"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "SearchReq": {
        "properties": {
          "query": {
            "type": "string",
            "title": "Query",
            "default": "",
            "maxLength": 1000
          },
          "k": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "K",
            "default": 10,
            "description": "Results to return. Each 10 results use 1 credit, rounded up. The Free plan returns at most 10; larger values are capped and the response carries a notice."
          },
          "ann_k": {
            "type": "integer",
            "maximum": 1000.0,
            "minimum": 1.0,
            "title": "Ann K",
            "default": 100
          },
          "bm25_k": {
            "type": "integer",
            "maximum": 1000.0,
            "minimum": 0.0,
            "title": "Bm25 K",
            "default": 50
          },
          "ann_ef": {
            "type": "integer",
            "maximum": 4096.0,
            "minimum": 64.0,
            "title": "Ann Ef",
            "default": 2048
          },
          "mode": {
            "type": "string",
            "enum": [
              "auto",
              "none",
              "text"
            ],
            "title": "Mode",
            "default": "auto",
            "description": "auto: text reranking for text, image similarity for image-only, fused similarity and text reranking for image-plus-text. text requires query text and forces caption reranking. none skips reranking."
          },
          "rerank": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rerank"
          },
          "rerank_k": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100,
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Rerank K",
            "default": 60,
            "description": "Rerank up to 100 candidates; default 60. Null uses 100. Larger values are rejected before billing."
          },
          "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"
          },
          "image_base64": {
            "type": "string",
            "maxLength": 6990572,
            "description": "JPEG, PNG or WebP base64 data URL or raw base64. Maximum 5 MiB decoded, 20 megapixels; still images only. Resized to a 1024-pixel edge before embedding. Requires a paid plan; returns 403 paid_feature on Free."
          },
          "image_url": {
            "type": "string",
            "maxLength": 4096,
            "description": "Public HTTPS image URL on port 443, without embedded credentials. Same image limits; private addresses blocked. Use this or image_base64, not both. Requires a paid plan; returns 403 paid_feature on Free."
          }
        },
        "type": "object",
        "required": [],
        "title": "SearchReq",
        "description": "Provide query text, one reference image, or both. image_base64 and image_url are mutually exclusive."
      },
      "SimilarReq": {
        "properties": {
          "asset_id": {
            "type": "string",
            "title": "Asset Id"
          },
          "k": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "K",
            "default": 10,
            "description": "Results to return. Each 10 results use 1 credit, rounded up."
          },
          "ann_k": {
            "type": "integer",
            "maximum": 1000.0,
            "minimum": 1.0,
            "title": "Ann K",
            "default": 100
          },
          "ann_ef": {
            "type": "integer",
            "maximum": 4096.0,
            "minimum": 64.0,
            "title": "Ann Ef",
            "default": 2048
          },
          "explain": {
            "type": "boolean",
            "title": "Explain",
            "default": false
          },
          "filters": {
            "$ref": "#/components/schemas/Filters"
          },
          "client_session": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Client Session"
          }
        },
        "type": "object",
        "required": [
          "asset_id"
        ],
        "title": "SimilarReq"
      },
      "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"
      },
      "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": "text, image, multimodal, none, or none (degraded). Multimodal scores fuse similarity and text ranks; scores are not probabilities."
          },
          "pool_size": {
            "type": "integer"
          },
          "reranked": {
            "type": "integer"
          },
          "backend": {
            "type": "string",
            "description": "Search responses report voyage."
          },
          "degraded": {
            "type": "string",
            "description": "Reranker unavailable; results are in retrieval order. This is a successful response and uses credits."
          },
          "relaxed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Default filters relaxed to fill results; explicit constraints are not relaxed."
          },
          "query_type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "image_text"
            ],
            "description": "Input modality for /v1/search."
          },
          "credits": {
            "$ref": "#/components/schemas/Credits"
          },
          "notice": {
            "$ref": "#/components/schemas/Notice"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "AssetResponse": {
        "type": "object",
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "format": {
            "type": "string"
          },
          "file": {
            "type": "string"
          },
          "thumb": {
            "type": "string"
          },
          "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"
              }
            }
          }
        }
      },
      "Credits": {
        "type": "object",
        "description": "Credits used by this call and credits left on the account. A search uses 1 credit per 10 results, rounded up, minimum 1.",
        "properties": {
          "charged": {
            "type": "integer",
            "description": "Credits used by this call."
          },
          "remaining": {
            "type": "integer",
            "description": "Credits left on the account after this call, including any credits from credit packs."
          },
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "starter",
              "pro",
              "scale",
              "custom"
            ],
            "description": "The account's plan id."
          }
        },
        "required": [
          "charged",
          "remaining",
          "plan"
        ]
      },
      "Notice": {
        "type": "object",
        "description": "Present only when the request was changed to fit the plan. On the Free plan, k above 10 is capped to 10 results.",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "max_results_capped"
            ]
          },
          "message": {
            "type": "string"
          },
          "requested": {
            "type": "integer",
            "description": "The k that was requested."
          },
          "max_results": {
            "type": "integer",
            "description": "The plan's maximum results per search."
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "CreditsExhaustedError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "enum": [
                  "credits_exhausted"
                ]
              },
              "plan": {
                "type": "string",
                "enum": [
                  "free",
                  "starter",
                  "pro",
                  "scale",
                  "custom"
                ]
              },
              "message": {
                "type": "string"
              },
              "upgrade_url": {
                "type": "string"
              },
              "next_plan": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The next plan up. Null on Scale and Custom."
              },
              "buy_credits_url": {
                "type": "string",
                "description": "Present on Scale and Custom, which can buy 10,000-credit packs for $40."
              }
            },
            "required": [
              "error",
              "plan",
              "message"
            ]
          }
        }
      },
      "PaidFeatureError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "enum": [
                  "paid_feature"
                ]
              },
              "feature": {
                "type": "string",
                "enum": [
                  "image_search",
                  "similar_search"
                ]
              },
              "plan": {
                "type": "string",
                "enum": [
                  "free"
                ]
              },
              "message": {
                "type": "string"
              },
              "upgrade_url": {
                "type": "string"
              }
            },
            "required": [
              "error",
              "feature",
              "plan",
              "message",
              "upgrade_url"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your Lightdrift API key. Usage is metered per query."
      }
    }
  },
  "servers": [
    {
      "url": "https://api.lightdrift.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ]
}
