{
  "openapi": "3.1.0",
  "info": {
    "title": "Flux API",
    "version": "1.0.0",
    "summary": "Web search API and Lineage API for AI agents: live ranked web results, and the passages that answer a question, compressed, with the people, places, organisations and dates named inline.",
    "description": "Three products behind one key.\n\n**Lineage** takes a document or a link and a question, and returns the passages that answer it with the people, places, organisations and dates resolved from the source itself. It selects from what you send rather than writing anything new.\n\n**Search** takes a query and returns ranked web results, each one able to carry the same passage selection and provenance.\n\n**Fetch** takes a URL and returns the whole page as markdown.\n\n## Authentication\n\n`Authorization: Bearer <key>` on every request. Keys are issued in the dashboard and the prefix says which pool the call draws from: `user_sk_` is a personal key, `org_sk_` is a workspace key. Enforcement binds to the workspace either way.\n\n## Request headers\n\n`Idempotency-Key` on `POST /api/v1/lineage`, `/search`, `/fetch` and `/batch`: 8 to 255 characters from `[A-Za-z0-9_:.-]`, remembered for 24 hours per workspace. A repeat with the same key and the same body returns the stored response with the header `Idempotency-Replayed: true` and is not charged again. The same key with a different body is a 409 `bad_request`. While the first request is still running, a repeat is a 409 `idempotency_in_progress` with `Retry-After: 5`. Only successful responses are stored, so a retry after a failure runs again. A key outside that format is ignored. Not supported on the OpenAI compatible endpoints.\n\n`X-Request-Id`: send your own (up to 64 characters from `[A-Za-z0-9_-]`) and it is echoed back on the response; otherwise one is generated. Lineage, Search, Fetch and the OpenAI compatible endpoints return it as a response header, and Lineage, Search and Fetch also return it as `request_id` in the body and as `error.request_id` on a failure. Quote it when contacting support.\n\n## Errors\n\nThe native endpoints answer every failure with `{\"error\": {\"code\", \"message\"}}`, plus `request_id` on Lineage, Search and Fetch. The OpenAI compatible endpoints use OpenAI's shape instead, `{\"error\": {\"message\", \"type\", \"param\", \"code\"}}`, so the OpenAI SDK can parse it. On a 429, wait the number of seconds in `Retry-After`; the default limit is 60 requests per minute per workspace.\n\n## Money\n\nCost is reported twice on every run. `cost_usd_ticks` is an integer where 1 USD = 10^10 ticks, and `cost_usd` is the same number as a fixed 10 place decimal string.\n\n`cost_usd` is a **string**, deliberately. It parses to a float in most languages, and a caller summing a column of floats gets a rounding error rather than an invoice. Reconcile on `cost_usd_ticks`.\n\nLineage is priced per million input tokens. Output tokens are counted and reported for context budgeting, and billed at their own rate, which is currently zero. Each query is a full pass over its document, so a document asked five questions is billed for five passes. Search is priced per 1,000 searches. Current rates are on [pricing](/pricing).\n\n## Machine readable\n\nThe OpenAPI document is at https://fluxsearch.io/api-reference/openapi.json and a summary written for agents is at https://fluxsearch.io/llms.txt. Both are generated from the same source as this page, so neither can fall behind it.",
    "contact": {
      "name": "Flux",
      "url": "https://fluxsearch.io/about",
      "email": "hello@fluxsearch.io"
    }
  },
  "servers": [
    {
      "url": "https://fluxsearch.io",
      "description": "Flux"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Lineage",
      "description": "Passages that answer a question, with their context."
    },
    {
      "name": "Search",
      "description": "Ranked web results, optionally enriched with Lineage."
    },
    {
      "name": "Fetch",
      "description": "One page as markdown."
    },
    {
      "name": "OpenAI compatible",
      "description": "Search and Lineage through the OpenAI SDK, in its request and error shapes."
    },
    {
      "name": "Account",
      "description": "The workspace balance."
    },
    {
      "name": "Batches",
      "description": "Many documents, drained asynchronously."
    }
  ],
  "paths": {
    "/api/v1/lineage": {
      "post": {
        "operationId": "createLineage",
        "tags": [
          "Lineage"
        ],
        "summary": "Get the passages that answer a question, compressed, with bylines naming people, places, organisations and dates",
        "description": "Send a document or a link and one or more questions. Get back the passages that answer each one, carrying the people, places, organisations and dates resolved from the source itself.\n\n`enriched_text` is the deliverable: the passage with its provenance written into it, per result. It is the string to hand to an LLM, and it is **never null**. When there was nothing to write in, it equals `text`, so it can be pasted unconditionally. `enrichment` says which of those you got.\n\n**Billed per pass: one document, read for one question.** Five queries over a document cost five times one, because each is a full pass over it; a batch of twenty documents costs twenty documents' worth, so batching is a latency optimisation rather than a pricing loophole. Up to 100 documents and 10 queries per document, and at most 200 passes (documents x queries) per request; above that the request is a 400 `bad_request`, so split it.\n\n**Partial failure, on a `documents` request.** A document that fails with `fetch_failed` or `bad_request` is listed in `errors[]` and the rest are answered. Any other failure, or the request running out of time, fails the whole request with 502 `upstream_error`. If no document could be read, the request is a 400 `bad_request` carrying the first document's reason.\n\nSend an `Idempotency-Key` header to make a retry safe: see Request headers.\n\nEvery measurement of the run is in `selection`. A `score` means nothing without `considered` and `threshold` beside it: those turn a bare number into a rank in a known population against a known bar, and they are what answers \"why was my sentence not returned\".\n\nNo part of the response names the stage that produced it. Which of our components tagged an entity, resolved a coreference or scored a passage is our implementation and it changes; what you get is the effect on your result.",
        "responses": {
          "200": {
            "description": "A single `text` or `url` with one query (or none) returns one `LineageResponse`; with several queries, a `LineageList`. A request with `documents` always returns a `LineageList`, even for one document and one query. A list has one entry per pass, in document order and then query order, each carrying `document_index`.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LineageResponseOrList"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`bad_request`: This `Idempotency-Key` was already used with a different request body. Use a new key for a new request. Not billed.\n\n`idempotency_in_progress`: A request with this `Idempotency-Key` is still running. Retry after the time in the Retry-After header (5 seconds) to get its stored response. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "8 to 255 characters from `[A-Za-z0-9_:.-]`, remembered for 24 hours. A repeat with the same body returns the stored response with `Idempotency-Replayed: true` and is not charged again.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 255,
              "pattern": "^[A-Za-z0-9_:.-]+$"
            }
          },
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Your own id for this request, echoed back in the `X-Request-Id` response header. Generated when absent. Quote it when contacting support.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LineageRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "post": {
        "operationId": "createSearch",
        "tags": [
          "Search"
        ],
        "summary": "Search the web and get ranked results, optionally with Lineage applied to each",
        "description": "Run a query and get ranked results back. Each result carries a URL, a title, a published date and the index's own summary, and the ones we read carry a `lineage` block: the same passage selection and provenance as `POST /api/v1/lineage`, applied to that page.\n\n`max_results` asks for results and `enrich` asks for how many of them to read. Both are clamped rather than rejected, because the price does not move with either: a value out of range costs nothing and a 400 would only be a way to fail a request we can serve. `enrich: 0` is the fast path, web results with no pages read, at the same price.\n\n`enrichment` on a result says what happened to it. `inline`: we read the page and wrote provenance into the passages. `none`: we read it and had nothing to write in. `skipped` is terminal, a PDF, a 404, a host that refuses us, or a result past the number of pages this request asked to have read. `pending` is a deadline rather than an error: the page was queued and the answer had to go out first, so a retry may well enrich it. **A skipped or pending result keeps its place in the array** with its title, URL and summary, so our capacity never shows up as your missing search result.\n\n`rank` is our order. It is three tiers rather than a score: pages we read that answered the query, then pages we read that did not, then pages we did not read, with the index's own order preserved inside each tier. A passage score is a rank within one document against that document's own threshold, so sorting across pages by it would compare numbers that were never on the same scale. `provider_rank` is where the index put each result, kept so the effect of our ordering is visible rather than asserted.\n\n`answer` is the index's own direct answer where it had one, not generated by us and not enriched, and null when there was none. `related_queries` is always an array, so a caller looping over suggestions never has to check first.\n\n**When a search node is down, search still answers**, and `X-Flux-Search-Mode` says how. `split`: the index answered and the pages were read elsewhere, so results still carry `lineage`, usually fewer than `enrich` asked for. `fallback`: the index answered alone and every result is `skipped`. The header is absent when the search ran normally, and the price is the same in all three cases. If the index cannot answer either, the response is a 503 `search_unavailable` and nothing is charged.\n\n**Priced per search, flat**, at the search rate on [pricing](/pricing). One call is one charge whether the index returned three results or twenty, and whether we managed to read all of them or none. `usage.searches` is the billed figure.\n\nSend an `Idempotency-Key` header to make a retry safe: see Request headers.",
        "responses": {
          "200": {
            "description": "The ranked results.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`bad_request`: This `Idempotency-Key` was already used with a different request body. Use a new key for a new request. Not billed.\n\n`idempotency_in_progress`: A request with this `Idempotency-Key` is still running. Retry after the time in the Retry-After header (5 seconds) to get its stored response. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`search_unavailable`: Search cannot run right now. Retry after the time in the Retry-After header. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "8 to 255 characters from `[A-Za-z0-9_:.-]`, remembered for 24 hours. A repeat with the same body returns the stored response with `Idempotency-Replayed: true` and is not charged again.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 255,
              "pattern": "^[A-Za-z0-9_:.-]+$"
            }
          },
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Your own id for this request, echoed back in the `X-Request-Id` response header. Generated when absent. Quote it when contacting support.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/fetch": {
      "post": {
        "operationId": "createFetch",
        "tags": [
          "Fetch"
        ],
        "summary": "Read one page and get it back as markdown",
        "description": "Send a URL and get the page back as clean markdown, with its title and published date. JavaScript-heavy pages are rendered before they are read.\n\nFetch returns the whole page. To get only the passages that answer a question, with provenance, use `POST /api/v1/lineage` instead.\n\n**Priced per fetch, flat**, at the fetch rate on [pricing](/pricing). A page that cannot be read answers 502 `fetch_failed` with the message \"The page could not be read.\" and is not billed. The site's own reason is not included.\n\nSend an `Idempotency-Key` header to make a retry safe: see Request headers.",
        "responses": {
          "200": {
            "description": "The page as markdown.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FetchResponse"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`bad_request`: This `Idempotency-Key` was already used with a different request body. Use a new key for a new request. Not billed.\n\n`idempotency_in_progress`: A request with this `Idempotency-Key` is still running. Retry after the time in the Retry-After header (5 seconds) to get its stored response. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`fetch_failed`: The page could not be read: it refused us, timed out or had no text. The message is always \"The page could not be read.\" and does not carry the site's reason. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "8 to 255 characters from `[A-Za-z0-9_:.-]`, remembered for 24 hours. A repeat with the same body returns the stored response with `Idempotency-Replayed: true` and is not charged again.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 255,
              "pattern": "^[A-Za-z0-9_:.-]+$"
            }
          },
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Your own id for this request, echoed back in the `X-Request-Id` response header. Generated when absent. Quote it when contacting support.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FetchRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "tags": [
          "OpenAI compatible"
        ],
        "summary": "Search or Lineage, through the OpenAI SDK",
        "description": "The same two products, in the shape the OpenAI SDK already speaks. Point `base_url` here and the client you have works unchanged.\n\n`model` picks the product. `flux-search-1` searches the web for the text of the last user message, reading every result (`enrich` is not passed through). `flux-lineage-1` reads a document. Send `url` and the last user message is your question: only the passages of that page that answer it come back. Without `url`, the message is the document and every passage comes back. For several questions in one call, use `POST /api/v1/lineage` with `queries`. `GET /api/v1/models` lists both.\n\n**Only the last user message is read.** Earlier messages, and any system message, are ignored. With `url` set on `flux-lineage-1`, the message is the question about that page.\n\n**The message content is the enriched text** (the selected sentences with their provenance written in), and the offsets live on `annotations`, which is where the Responses API puts citations and therefore where an SDK already looks.\n\n**Two annotation types sit on the same content.** `url_citation` is OpenAI's own citation shape, so a client that already renders web-search citations renders ours with no Flux-specific code. `provenance` carries what nobody else has: the entities, their canonical names, the score, and for Lineage the offsets back into the document you sent. Ignore the second and you still get working citations.\n\n**Domain scoping is read from the tool config you already emit.** A `web_search` or `web_search_preview` entry in `tools` carrying `filters.allowed_domains` is honoured, as is a top-level `filters`.\n\n`response_format` naming `flux.search` or `flux.lineage` returns the native records instead of prose, and `annotations` is then an empty array. Any other name is a `bad_request` that lists the real ones, and a caller-supplied `json_schema.schema` is refused rather than ignored: extraction into your own schema is not supported yet, and silently disregarding it would leave you parsing a shape we never promised.\n\n**Streaming is supported, and it is worth being exact about what it does.** `stream: true` returns server-sent events in the format the OpenAI SDKs parse: `chat.completion.chunk` frames ending in `data: [DONE]` here, named `response.*` events on `/responses`. The first frame is sent immediately, and a comment frame every ten seconds keeps a long request from being closed as idle by a proxy or a client read timeout. **It does not make the answer arrive sooner.** The pipeline produces a result only when it finishes, so the content arrives as one delta at the end; a stream shortens time to first byte, not time to first token.\n\nAnything that can be rejected before the work starts still is, with a real status: an invalid request is a 400 and an empty workspace a 402. A failure after the stream has opened - the service saturated, or a balance drained by a concurrent request - arrives in-band as an `error`, because the 200 has already been sent. SDKs retry a 429 status automatically but not an in-band error, so a caller relying on automatic backoff under load should not stream. `stream_options.include_usage` adds a final usage chunk, as OpenAI does. Billing is unchanged: a search is priced per search, Lineage per input token.\n\nErrors here use OpenAI's shape, `{\"error\": {\"message\", \"type\", \"param\", \"code\"}}`, with the code from the error table in both `type` and `code`, so the OpenAI SDK raises its usual typed exceptions. The body carries no `request_id`; the `X-Request-Id` response header does. `Idempotency-Key` is not supported on these endpoints.",
        "responses": {
          "200": {
            "description": "One assistant message, with annotations.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`search_unavailable`: Search cannot run right now. Retry after the time in the Retry-After header. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Your own id for this request, echoed back in the `X-Request-Id` response header. Generated when absent. Quote it when contacting support.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/responses": {
      "post": {
        "operationId": "createResponse",
        "tags": [
          "OpenAI compatible"
        ],
        "summary": "The same request, in the Responses API envelope",
        "description": "Identical to `POST /api/v1/chat/completions` in every respect except the envelope, including its error shape and the rule that only the last user message is read. Carried because it is the API OpenAI is steering people to, and because its content model has somewhere native to put annotations: `output[].content[].annotations` is exactly where an SDK looks for citations.\n\n`usage` uses `input_tokens` and `output_tokens` here, matching the Responses API, where chat/completions uses `prompt_tokens` and `completion_tokens`. The two genuinely differ, and an SDK reads whichever belongs to the endpoint it called.\n\n**Structured output** is selected by the Responses API's `text.format` (`{\"type\": \"json_schema\", \"name\": \"flux.lineage\"}`), or by `response_format` in the chat/completions shape. When both are sent, `response_format` wins.\n\n**Python SDK: check `annotation.type`, not the annotation's class.** The official Python client types Responses annotations as a closed set of OpenAI's own kinds. A `provenance` annotation is not one of them, so the SDK parses it into its nearest class (`AnnotationFileCitation`) and logs a pydantic serialization warning when the response is dumped. Nothing is lost: `type` is still `provenance` and `entities`, `source_start` and `score` are all present. The TypeScript SDK and `/chat/completions` are unaffected.",
        "responses": {
          "200": {
            "description": "One response object.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponsesObject"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`search_unavailable`: Search cannot run right now. Retry after the time in the Retry-After header. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Your own id for this request, echoed back in the `X-Request-Id` response header. Generated when absent. Quote it when contacting support.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponsesRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/models": {
      "get": {
        "operationId": "listModels",
        "tags": [
          "OpenAI compatible"
        ],
        "summary": "The two model names",
        "description": "What an SDK probes before anything else. **Unauthenticated**, deliberately: it lists two names and two sentences, there is nothing here worth a key, and requiring one turns the first call a new integrator makes into a 401 they have to debug. Every endpoint that costs money is still behind a key.",
        "responses": {
          "200": {
            "description": "The available models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/account": {
      "get": {
        "operationId": "getAccount",
        "tags": [
          "Account"
        ],
        "summary": "The workspace balance",
        "description": "Your balance is never in a Lineage or Search response. It is account state rather than a property of one request, it does not belong in something a caller may log or forward, and it lives here.\n\n`balance.usd_ticks` is the authority and `balance.usd` is the same number as a decimal string, the same contract as `cost_usd` on a run. `balance.input_tokens` is what the balance buys at the Lineage rate, which is the number somebody sizing a job wants and the one a dollar figure makes them compute themselves. It is 0 when prices cannot be read; the dollar figures are still reported.",
        "responses": {
          "200": {
            "description": "The balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/batch": {
      "post": {
        "operationId": "createBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Submit many documents and come back for the results",
        "description": "The body is JSONL, one Lineage request per line, and the answer is a job handle. A line can ask several `queries`; each is a pass and is billed as one, and that line's result is a `LineageList`. Nothing is processed while you wait: the work is written down, acknowledged, and drained afterwards. A batch that takes four hours cannot be a request that takes four hours, and holding a connection open for one only guarantees it dies.\n\nPoll `GET /api/v1/batch/{handle}` for progress and read `GET /api/v1/batch/{handle}/results` for finished items. A body above 32 MB is rejected rather than truncated, as HTTP 413 carrying a `bad_request` code.\n\n**Billed per item, when its result is first read**, at the Lineage rate for its passes and tokens: the same price a synchronous request pays. Submitting charges nothing, and failed items are free. A submission is refused with `insufficient_credits` when the balance cannot cover an estimate of the whole batch: text at four characters a token, each URL at 15,000 tokens, times its passes.\n\nSend an `Idempotency-Key` header so a retried submit does not create a second job: see Request headers.",
        "responses": {
          "202": {
            "description": "Accepted: `{id, object: \"batch\", status: \"queued\", total}`. The handle in `id` is what every later call uses.",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds at which the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchJob"
                }
              }
            }
          },
          "400": {
            "description": "`bad_request`: Something in the request is wrong, or a page could not be fetched. The message says which, including the site's own reason. Retrying the same request fails the same way. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "`insufficient_credits`: Your balance is too low for this request. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`bad_request`: This `Idempotency-Key` was already used with a different request body. Use a new key for a new request. Not billed.\n\n`idempotency_in_progress`: A request with this `Idempotency-Key` is still running. Retry after the time in the Retry-After header (5 seconds) to get its stored response. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: Too many requests. Either this workspace sent more than its limit (60 requests per minute by default), or the service is saturated, in which case Retry-After is 5. Wait the number of seconds in the Retry-After header either way. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "8 to 255 characters from `[A-Za-z0-9_:.-]`, remembered for 24 hours. A repeat with the same body returns the stored response with `Idempotency-Replayed: true` and is not charged again.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 255,
              "pattern": "^[A-Za-z0-9_:.-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One JSON object per line, each in the shape of a `LineageRequest`.",
          "content": {
            "application/x-ndjson": {
              "schema": {
                "$ref": "#/components/schemas/BatchSubmission"
              }
            }
          }
        }
      }
    },
    "/api/v1/batch/{handle}": {
      "get": {
        "operationId": "getBatch",
        "tags": [
          "Batches"
        ],
        "summary": "How far along a batch is",
        "description": "Cheap to call: a grouped count, no GPU involved. Poll it as often as is useful.",
        "responses": {
          "200": {
            "description": "The job and its counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchJob"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: No batch matches this handle. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "The handle returned by `POST /api/v1/batch`.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/batch/{handle}/results": {
      "get": {
        "operationId": "getBatchResults",
        "tags": [
          "Batches"
        ],
        "summary": "Finished items, as NDJSON, from a cursor",
        "description": "Streamed rather than buffered, so a large result set never has to exist in memory at once.\n\nOne line per finished item, each `{seq, status, custom_id?, response}`. A `done` item's `response` is a `LineageResponse`, or a `LineageList` when that line asked several `queries`; an `error` or `unpaid` item carries an error object there instead.\n\n**Each `done` item is charged the first time it is read**, at the `cost_usd` its line quotes. Reading it again charges nothing. When the balance cannot cover an item it comes back `unpaid` with an `insufficient_credits` error, and the items already paid for are still returned; read it again after topping up to receive it.\n\n**The cursor is yours to keep.** A reader that drops comes back with the last `seq` it saw and misses nothing. Passing nothing starts from the beginning.",
        "responses": {
          "200": {
            "description": "One JSON object per line.",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: The key is missing, invalid or revoked. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: No batch matches this handle. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`upstream_error`: Something failed on our side. Not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`pricing_unavailable`: Prices could not be read, so the request was refused before any work. Retry shortly: Lineage, Search and Fetch send `Retry-After: 30`. Not billed.\n\n`not_configured`: The service is not available. Not billed.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "The handle returned by `POST /api/v1/batch`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The last `seq` you read. Omit, or send -1, to start from the beginning.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "`Authorization: Bearer <key>`. A `user_sk_` key draws from a personal pool and an `org_sk_` key from a workspace pool; enforcement binds to the workspace either way. Keys are issued in the dashboard, and only their hash is stored, so a key is shown once."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The native error envelope. The OpenAI compatible endpoints use OpenAI's shape instead: `{\"error\": {\"message\", \"type\", \"param\", \"code\"}}`.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "bad_request",
                  "unauthorized",
                  "insufficient_credits",
                  "not_found",
                  "idempotency_in_progress",
                  "rate_limited",
                  "upstream_error",
                  "fetch_failed",
                  "pricing_unavailable",
                  "search_unavailable",
                  "not_configured"
                ]
              },
              "message": {
                "type": "string",
                "description": "Plain text, safe to show a person."
              },
              "request_id": {
                "type": "string",
                "description": "The id of this request, as in the `X-Request-Id` header. Present on Lineage, Search and Fetch."
              }
            }
          }
        },
        "examples": [
          {
            "error": {
              "code": "bad_request",
              "message": "The page returned HTTP 429."
            }
          }
        ]
      },
      "Annotation": {
        "type": "object",
        "description": "One entry per **mention**, so a passage naming Acme twice gives two annotations.\n\n`start_index` and `end_index` are into that result's `text`, and they are **code points rather than UTF-16 units**, so a JavaScript client will disagree on text outside the Basic Multilingual Plane.\n\nThere is no confidence field. How many of our stages agreed is our pipeline described under a name that reads as a probability.",
        "required": [
          "type",
          "text",
          "start_index",
          "end_index",
          "canonical"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "What kind of thing it is: person, organisation, place, product, event or time. More kinds may be added.",
            "examples": [
              "organisation",
              "place"
            ]
          },
          "text": {
            "type": "string",
            "description": "The mention as it appears in the source."
          },
          "start_index": {
            "type": "integer",
            "minimum": 0
          },
          "end_index": {
            "type": "integer",
            "minimum": 0
          },
          "canonical": {
            "type": [
              "string",
              "null"
            ],
            "description": "The resolved form: an exact date for a time, or the name a word like \"she\" stands for. Null when there is nothing to resolve."
          },
          "year_inferred": {
            "type": "boolean",
            "const": true,
            "description": "Present on a time whose year the text did not state: \"as of May 26\" placed in a year from the publish date or from another date in the document. Treat that year as ours, not the source's. Absent when the year was stated."
          }
        }
      },
      "SearchEnrichment": {
        "type": "string",
        "enum": [
          "inline",
          "none",
          "skipped",
          "pending"
        ],
        "description": "What happened to this search result.\n\n**A different type from `Enrichment`, which Lineage uses, and the difference is real rather than an oversight.** A search decides how many pages to read and can run out of deadline, so it has two states a Lineage call cannot reach: `skipped` is terminal - a PDF, a 404, a host that refuses us, or a result past the number of pages this request asked to have read - and `pending` is a deadline rather than an error, so a retry may well enrich it.\n\n**A skipped or pending result keeps its place in the array** with its title, URL and summary, so our capacity never shows up as your missing search result."
      },
      "Enrichment": {
        "type": "string",
        "enum": [
          "inline",
          "none"
        ],
        "description": "Whether the passage came back with its provenance written into it.\n\n**Lineage only, and deliberately a different type from `SearchEnrichment`.** A search result can also be `skipped` or `pending`, because a search decides how many pages to read and can run out of deadline; a Lineage request has already been handed its document, so neither state can arise. They share a field name and not a domain, which is why they are two schemas - a generated client gets two enums rather than one that is wrong on one endpoint.\n\nAn enum rather than a boolean: a boolean is right today and wrong the first time there is a second marker format, and `is_enriched: true` could not say which one you got.\n\n**`\"none\"` beside a non-empty `annotations` is legal, and is the case worth knowing about:** we found entities and could not place them inline. The annotations are still the machine readable ground truth underneath."
      },
      "LineageResult": {
        "type": "object",
        "required": [
          "id",
          "source_id",
          "text",
          "enriched_text",
          "enrichment",
          "span",
          "score",
          "annotations"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "res_1"
            ]
          },
          "source_id": {
            "type": "string",
            "description": "Which entry of `sources` this came from.",
            "examples": [
              "src_1"
            ]
          },
          "text": {
            "type": "string",
            "description": "The passage exactly as it appears in your document."
          },
          "enriched_text": {
            "type": "string",
            "description": "The passage with context added only where it needs it, such as an exact date or the name behind \"she\". Never null: when there is nothing to add, it equals `text`."
          },
          "enrichment": {
            "$ref": "#/components/schemas/Enrichment"
          },
          "span": {
            "type": "object",
            "description": "Where the passage starts and ends in the document you sent.",
            "required": [
              "start",
              "end"
            ],
            "properties": {
              "start": {
                "type": "integer",
                "minimum": 0
              },
              "end": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "description": "How well the passage answers the query. Higher is better. Passages below `selection.threshold` are not returned."
          },
          "annotations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Annotation"
            }
          }
        }
      },
      "Selection": {
        "type": "object",
        "description": "What happened to the document. Every measurement of the run is here rather than beside the money.",
        "required": [
          "score_type",
          "threshold",
          "considered",
          "returned",
          "examined_tokens",
          "enriched_results",
          "retained_ratio",
          "reduction_ratio"
        ],
        "properties": {
          "score_type": {
            "type": "object",
            "description": "Stated rather than implied. A bare number called `score` says nothing about direction or about whether it compares across requests, and both questions get asked.",
            "required": [
              "name",
              "higher_is_better",
              "calibrated"
            ],
            "properties": {
              "name": {
                "type": "string",
                "examples": [
                  "relevance"
                ]
              },
              "higher_is_better": {
                "type": "boolean"
              },
              "calibrated": {
                "type": "boolean",
                "description": "False means scores are comparable within a request and not across them."
              }
            }
          },
          "threshold": {
            "type": [
              "number",
              "null"
            ],
            "description": "What a score had to beat. Null in survey mode, where nothing was filtered."
          },
          "considered": {
            "type": "integer",
            "description": "Passages scored. This is what makes `score` legible: a percentile is meaningless without its population, and \"why was my sentence not returned\" is unanswerable without it."
          },
          "returned": {
            "type": "integer"
          },
          "examined_tokens": {
            "type": "integer",
            "description": "Below `usage.input_tokens` means the tail of the document was never read. This is the effect of a truncation, stated without naming the stage that truncated."
          },
          "enriched_results": {
            "type": "integer",
            "description": "How many results came back with their provenance written in. Zero across a whole response is how a systemic enrichment failure is visible without walking every result."
          },
          "retained_ratio": {
            "type": "number",
            "description": "`usage.output_tokens / usage.input_tokens`, measured against the **enriched** text, because that is what you send onward and pay your own provider for. **It can exceed 1, and it is not clamped:** that means the provenance markers came to more than the selection saved, which is the honest answer on a short document and on any survey mode call. Branch on this against a budget rather than on the sign of `reduction_ratio`."
          },
          "reduction_ratio": {
            "type": "number",
            "description": "`1 - retained_ratio`, and negative whenever `retained_ratio` exceeds 1. Not clamped, because clamping it to zero would hide a real cost."
          }
        }
      },
      "LineageUsage": {
        "type": "object",
        "description": "Tokens and money. Nothing else.\n\n**There is no `total_tokens`, deliberately.** It would double-count the source material.\n\n**Your balance is not here.** It is account state rather than a property of one request, and it lives at `GET /api/v1/account`.",
        "required": [
          "input_tokens",
          "output_tokens",
          "cost_usd",
          "cost_usd_ticks"
        ],
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "All source text processed. This is the billed figure, and it is the sum of `sources[].input_tokens`."
          },
          "output_tokens": {
            "type": "integer",
            "description": "The final emitted enriched context, provenance markers included - the tokens in the `enriched_text` you receive, NOT the raw passages. It is sourced from the pipeline's `enriched_tokens`, and the distinction matters because it is what you are quoted on: a passage that gained a lot of markers costs more than the same passage bare. Reported for context budgeting, billed at the output rate on [pricing](/pricing)."
          },
          "cost_usd": {
            "type": "string",
            "description": "The same number as `cost_usd_ticks`, as a decimal string fixed at 10 places. **A string, not a number:** it parses to a float in most languages, and a caller summing a column of floats gets a rounding error rather than an invoice.",
            "examples": [
              "0.0042060000"
            ]
          },
          "cost_usd_ticks": {
            "type": "integer",
            "description": "The authoritative cost. 1 USD = 10^10 ticks. Reconcile on this.",
            "examples": [
              42060000
            ]
          }
        }
      },
      "LineageSource": {
        "type": "object",
        "required": [
          "id",
          "url",
          "published_at",
          "input_tokens"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "src_1"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The URL we resolved to, or the one you sent when there was no resolved one to report. Null for a run over text you supplied."
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `published` you sent, or else the date the page gives itself in its metadata. ISO, at the precision known. Only the `published` you send is used to place dates that have no year.",
            "examples": [
              "2026-04-23"
            ]
          },
          "input_tokens": {
            "type": "integer"
          }
        }
      },
      "LineageRequest": {
        "type": "object",
        "description": "Send **either** `text` or `url`, plus the questions in `queries` (or one question in `query`).\n\nEach query is a full pass over the document and is billed as one. Without `queries`, every passage is returned in one pass.\n\n`documents` is an explicit batch: an array of objects each carrying its own `text` or `url`, up to 100 per request. Outer fields apply to any item that omits its own, so one `queries` can cover the whole batch; an item's own `queries` replaces it. An item may also carry its own `published`.\n\nFields not listed here reach the service untouched.",
        "properties": {
          "text": {
            "type": "string",
            "description": "The document to read. Up to 60,000 characters.",
            "maxLength": 60000
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "A page for Flux to fetch instead of sending `text`. If the site refuses, the response is a `bad_request` with the site's reason, and nothing is charged."
          },
          "queries": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "The questions to answer, up to 10, each a full pass over the document billed as one. Each comes back as its own entry. Without it, every passage is returned and `query` in the response is null."
          },
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "A single question, the same as `queries` with one entry. Sending both `query` and `queries` is a 400 `bad_request`."
          },
          "published": {
            "type": "string",
            "description": "When the text was published, as an ISO date. Used to place relative dates such as \"last April\". May also be set per document.",
            "examples": [
              "2026-04-23"
            ]
          },
          "documents": {
            "type": "array",
            "maxItems": 100,
            "description": "Several documents in one request, each with its own `text` or `url`. Up to 100.",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "queries": {
                  "type": "array",
                  "maxItems": 10,
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "query": {
                  "type": "string",
                  "minLength": 1
                },
                "published": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true,
        "examples": [
          {
            "url": "https://example.com/article",
            "queries": [
              "revenue"
            ]
          },
          {
            "text": "Acme Corp announced record revenue in Berlin. Its chief executive, Jane Doe, said demand had doubled.",
            "queries": [
              "revenue",
              "who runs Acme"
            ]
          }
        ]
      },
      "LineageResponse": {
        "type": "object",
        "required": [
          "request_id",
          "status",
          "query",
          "sources",
          "results",
          "selection",
          "usage"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "examples": [
              "req_9f3c2a"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ],
            "description": "**Completed or failed, with nothing in between.** It used to carry `degraded` when a stage fell back, which said something broke in our pipeline without saying what. `selection` says it better and says it in your terms: a highlighter that fell back and returned everything shows `retained_ratio` near 1, and an enrichment stage that failed shows `enriched_results` at 0."
          },
          "query": {
            "type": [
              "string",
              "null"
            ],
            "description": "The question this pass answered. Null when nothing was asked."
          },
          "document_index": {
            "type": "integer",
            "description": "Which document this pass read, as its position in `documents` (0 for a single document). Present on every entry of a `LineageList`."
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineageSource"
            }
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineageResult"
            }
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          },
          "usage": {
            "$ref": "#/components/schemas/LineageUsage"
          }
        }
      },
      "LineageList": {
        "type": "object",
        "description": "What a request with more than one pass, or any request with `documents`, answers with: a `documents` request is always a list, even for one document and one query. One entry per pass, in document order and then query order. A list, because collapsing several passes into one object loses which result answered which question about which input.",
        "required": [
          "object",
          "data",
          "usage"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "description": "One `LineageResponse` per pass, each carrying `document_index`.",
            "items": {
              "$ref": "#/components/schemas/LineageResponse"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/LineageUsage",
            "description": "The whole request: the sum of every pass, and what was charged."
          },
          "errors": {
            "type": "array",
            "description": "On a `documents` request, every document that could not be read: a site that blocks automated access, a 403, a page with no text. The other documents are answered and billed as normal, and an unread document costs nothing. Empty when every document was read. Only `fetch_failed` and `bad_request` failures are listed here. Any other failure, or the request running out of time, fails the whole request with 502 `upstream_error`, and a request where no document could be read fails with 400 `bad_request`.",
            "items": {
              "type": "object",
              "required": [
                "document_index",
                "code",
                "message",
                "url"
              ],
              "properties": {
                "document_index": {
                  "type": "integer",
                  "minimum": 0
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "fetch_failed",
                    "bad_request"
                  ]
                },
                "message": {
                  "type": "string",
                  "examples": [
                    "The site blocked automated access."
                  ]
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "LineageResponseOrList": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/LineageResponse"
          },
          {
            "$ref": "#/components/schemas/LineageList"
          }
        ]
      },
      "FetchRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "A public http or https address.",
            "examples": [
              "https://en.wikipedia.org/wiki/Retrieval-augmented_generation"
            ]
          }
        }
      },
      "FetchResponse": {
        "type": "object",
        "required": [
          "request_id",
          "url",
          "title",
          "published_at",
          "markdown",
          "usage"
        ],
        "properties": {
          "request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "description": "Where the page was read from, after redirects."
          },
          "title": {
            "type": "string",
            "description": "The page title. Empty if it has none."
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The date the page gives itself, as ISO. Null when it gives none."
          },
          "markdown": {
            "type": "string",
            "description": "The readable page as markdown."
          },
          "usage": {
            "type": "object",
            "required": [
              "fetches",
              "cost_usd",
              "cost_usd_ticks"
            ],
            "properties": {
              "fetches": {
                "type": "integer",
                "const": 1
              },
              "cost_usd": {
                "type": "string",
                "examples": [
                  "0.0010000000"
                ]
              },
              "cost_usd_ticks": {
                "type": "integer"
              }
            }
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "description": "The query, and how much work to do on it. Only the fields below are read; any other field is ignored.",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000,
            "description": "What to search for. Must not be empty. Up to 1,000 characters.",
            "examples": [
              "acme corp revenue"
            ]
          },
          "max_results": {
            "type": "integer",
            "default": 10,
            "minimum": 1,
            "maximum": 20,
            "description": "The most results to return, from 1 to 20. A value outside that range is moved inside it. You may get fewer."
          },
          "filters": {
            "$ref": "#/components/schemas/SearchFilters"
          },
          "enrich": {
            "type": "integer",
            "minimum": 0,
            "description": "How many of the results to read for passages, up to `max_results`. Defaults to all of them. `0` returns results without reading any pages, which is fastest."
          }
        },
        "additionalProperties": true,
        "examples": [
          {
            "query": "acme corp revenue",
            "max_results": 10,
            "enrich": 5
          },
          {
            "query": "who runs barclays",
            "filters": {
              "allowed_domains": [
                "home.barclays"
              ]
            }
          }
        ]
      },
      "SearchFilters": {
        "type": "object",
        "description": "Scope the search to, or away from, particular sites.\n\nThis is OpenAI's `web_search` filter shape verbatim, so a tool config you already emit for their API works here unchanged. It is echoed back on the response: no index we can buy has a native allow-list, so scoping is translated into `site:` operators, and a translation that could not be expressed has to be visible rather than silent.\n\nOver the limits below the request is refused rather than truncated. Search indexes drop excess terms instead of erroring, so a quietly shortened allow-list would return results from outside the filter while the response claimed otherwise.\n\nKeys other than the two below are ignored.",
        "properties": {
          "allowed_domains": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string"
            },
            "description": "Only return pages from these sites, up to 10. A full URL is reduced to its host. `www.` counts as part of the host.",
            "examples": [
              [
                "home.barclays"
              ]
            ]
          },
          "blocked_domains": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string"
            },
            "description": "Never return pages from these sites, up to 20. A site in both lists is excluded.",
            "examples": [
              [
                "pinterest.com"
              ]
            ]
          }
        },
        "additionalProperties": true
      },
      "ChatCompletionRequest": {
        "type": "object",
        "description": "An OpenAI chat request. Only the fields below are read; anything else an SDK sends is ignored rather than rejected, so a client configured for another provider does not have to be stripped down first.",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "flux-search-1",
              "flux-lineage-1"
            ],
            "description": "Which product to run. `GET /api/v1/models` lists them."
          },
          "messages": {
            "type": "array",
            "description": "The last `user` message is the query for `flux-search-1`, or the document for `flux-lineage-1`. Earlier messages, including any `system` message, are ignored: this answers one turn from one message, and joining a history together would search for something nobody asked. With `url` set, `flux-lineage-1` reads the page and the message is the question about it.",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "system",
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string"
                }
              }
            }
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "`flux-lineage-1` only. Fetch and read this page; the message text becomes the question, and only the passages that answer it come back. This is how you ask us to go and get the page rather than reading what you pasted."
          },
          "max_results": {
            "type": "integer",
            "description": "`flux-search-1` only. As on `/search`."
          },
          "filters": {
            "$ref": "#/components/schemas/SearchFilters"
          },
          "tools": {
            "type": "array",
            "description": "Read only for a `web_search` or `web_search_preview` entry carrying `filters`, so an agent framework's existing tool config scopes the search with no change. No tool is ever called.",
            "items": {
              "type": "object"
            }
          },
          "response_format": {
            "type": "object",
            "description": "`{\"type\": \"json_schema\", \"json_schema\": {\"name\": \"flux.search\"}}` returns the native records instead of prose. `flux.search` and `flux.lineage` are the published names."
          },
          "stream": {
            "type": "boolean",
            "description": "Server-sent events when `true`. The first frame is immediate and the connection is kept alive during the run, but the content itself arrives in one piece when the run finishes (see the endpoint description)."
          },
          "stream_options": {
            "type": "object",
            "description": "`include_usage: true` adds a final chunk carrying `usage`, with an empty `choices` array.",
            "properties": {
              "include_usage": {
                "type": "boolean"
              }
            }
          }
        },
        "additionalProperties": true
      },
      "CompatAnnotation": {
        "type": "object",
        "description": "Either a `url_citation` (OpenAI's own citation shape, which existing clients render without knowing anything about us) or a `provenance` entry carrying the entities, the score, and for Lineage the offsets back into the document you sent.\n\n`start_index` and `end_index` are **code points** into the message content, not UTF-16 units.",
        "required": [
          "type",
          "start_index",
          "end_index"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "url_citation",
              "provenance"
            ]
          },
          "start_index": {
            "type": "integer"
          },
          "end_index": {
            "type": "integer"
          },
          "url": {
            "type": "string",
            "description": "`url_citation` only. The page the passage came from."
          },
          "title": {
            "type": "string",
            "description": "`url_citation` only. The title of that page."
          },
          "source_start": {
            "type": [
              "integer",
              "null"
            ],
            "description": "`provenance` only. Where the passage starts in the document you sent. Null for search results."
          },
          "source_end": {
            "type": [
              "integer",
              "null"
            ]
          },
          "score": {
            "type": [
              "number",
              "null"
            ]
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompatEntity"
            }
          }
        }
      },
      "CompatEntity": {
        "type": "object",
        "description": "One entity inside a `provenance` annotation. No offsets: the annotation itself carries the span, and an entity is what was found inside it.",
        "required": [
          "type",
          "text",
          "canonical"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "What kind of thing it is: person, organisation, place, product, event or time."
          },
          "text": {
            "type": "string",
            "description": "As written in the passage."
          },
          "canonical": {
            "type": [
              "string",
              "null"
            ],
            "description": "The resolved form: an exact date for a time, or the name a word like \"she\" stands for. Null when there is nothing to resolve."
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "description": "An OpenAI chat completion. `finish_reason` is always `stop`: we answer one turn, there is no length cap to hit and no tool call to make.",
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "chatcmpl_9f2c..."
            ]
          },
          "object": {
            "type": "string",
            "enum": [
              "chat.completion"
            ]
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string",
                      "enum": [
                        "assistant"
                      ]
                    },
                    "content": {
                      "type": "string"
                    },
                    "annotations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CompatAnnotation"
                      },
                      "description": "An empty array in structured mode, because the offsets index into prose."
                    }
                  }
                },
                "finish_reason": {
                  "type": "string",
                  "enum": [
                    "stop"
                  ]
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "`prompt_tokens` / `completion_tokens`, as chat/completions uses.",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ResponsesRequest": {
        "type": "object",
        "description": "The Responses API request. Identical to `ChatCompletionRequest` except that the prompt arrives as `input` rather than `messages`, which is the whole reason this schema exists separately. Documenting the endpoint with the chat schema made the idiomatic request formally invalid, because that one requires `messages` and has no `input` at all.",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "flux-search-1",
              "flux-lineage-1"
            ],
            "description": "Which product to run. `GET /api/v1/models` lists them."
          },
          "input": {
            "description": "A string, or the message array the Responses API accepts. Only the last `user` entry is read: the query for `flux-search-1`, or the document for `flux-lineage-1`. Earlier entries are ignored. With `url` set, it is not used.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ]
          },
          "url": {
            "type": "string",
            "description": "Lineage only. Fetch and read this page; the message text becomes the question about it."
          },
          "max_results": {
            "type": "integer",
            "description": "Search only. Clamped to 1-20."
          },
          "filters": {
            "$ref": "#/components/schemas/SearchFilters"
          },
          "response_format": {
            "type": "object",
            "description": "Selects structured output, as on chat/completions: `{\"type\": \"json_schema\", \"json_schema\": {\"name\": \"flux.search\"}}` or `flux.lineage` returns the native records instead of prose. On /responses, `text.format` in the Responses API's flattened shape does the same, and this field wins when both are sent."
          },
          "stream": {
            "type": "boolean",
            "description": "Named `response.*` server-sent events when `true`, ending in `response.completed`. Immediate first frame and a kept-alive connection; the content still arrives in one piece at the end."
          }
        },
        "additionalProperties": true
      },
      "ResponsesObject": {
        "type": "object",
        "description": "The same content in the Responses API envelope. `usage` uses `input_tokens` / `output_tokens` here.",
        "required": [
          "id",
          "object",
          "model",
          "status",
          "output",
          "output_text",
          "usage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "resp_9f2c..."
            ]
          },
          "object": {
            "type": "string",
            "enum": [
              "response"
            ]
          },
          "created_at": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ]
          },
          "output": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "output_text": {
            "type": "string",
            "description": "The convenience field the SDK exposes as `response.output_text`."
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "required": [
          "object",
          "data"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "examples": [
                    "flux-search-1"
                  ]
                },
                "object": {
                  "type": "string",
                  "enum": [
                    "model"
                  ]
                },
                "created": {
                  "type": "integer"
                },
                "owned_by": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SearchLineage": {
        "type": "object",
        "description": "The Lineage block for one result: the same passage selection and provenance as `POST /api/v1/lineage`, applied to that page, produced by the same mapper rather than by a second one that agrees with it today.\n\nNo `sources` array, because inside a search result there is exactly one source and it is the enclosing result - so `LineageResult.source_id` is rewritten to that result's own id (`res_1`, `res_2`, ...) rather than the `src_1` a standalone Lineage call returns. Join it to the search result you found it under, not to a sources array that is not there. No `usage` either: search is priced per search, so the per-page token counts are not what you are charged on.",
        "required": [
          "results",
          "selection"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineageResult"
            }
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "id",
          "rank",
          "provider_rank",
          "url",
          "title",
          "published_at",
          "snippet",
          "enrichment",
          "lineage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "res_1"
            ]
          },
          "rank": {
            "type": "integer",
            "description": "Position in the results, starting at 1.",
            "minimum": 1
          },
          "provider_rank": {
            "type": "integer",
            "description": "Where the search index ranked it, before Flux reordered the results."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The page address. Always present."
          },
          "title": {
            "type": "string",
            "description": "The page title. Empty if the index has none."
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the page was published, if the search index knows, as ISO at the precision known: \"2024-09-24\", \"2026-07\" for \"3 months ago\", \"2022\" for \"4 years ago\". Otherwise null.",
            "examples": [
              "2024-09-24"
            ]
          },
          "snippet": {
            "type": "string",
            "description": "The search index's summary of the page. Flux does not change it."
          },
          "enrichment": {
            "$ref": "#/components/schemas/SearchEnrichment"
          },
          "lineage": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SearchLineage"
              },
              {
                "type": "null"
              }
            ],
            "description": "The passages Flux read from this page. Null when the page was not read."
          }
        }
      },
      "SearchAnswer": {
        "type": "object",
        "description": "The index's own direct answer, where it had one. Not generated by us, and not enriched.",
        "required": [
          "text",
          "url",
          "published_at"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SearchUsage": {
        "type": "object",
        "description": "Searches and money, at the search rate on [pricing](/pricing). The tick and string pair follows the same rule as Lineage: the integer is the authority, the string is for display.",
        "required": [
          "searches",
          "results_returned",
          "results_enriched",
          "cost_usd",
          "cost_usd_ticks"
        ],
        "properties": {
          "searches": {
            "type": "integer",
            "description": "The billed unit. Stated rather than left implied at one, because an invoice is reconciled by multiplying a count by a price and the count has to be in the receipt."
          },
          "results_returned": {
            "type": "integer"
          },
          "results_enriched": {
            "type": "integer",
            "description": "How many results came back with a `lineage` block, whether or not any passage in one got its provenance written in. `results_returned` minus this is what the deadline cost. Counting only `inline` would report a page we read end to end as a failure because it happened to name nobody."
          },
          "cost_usd": {
            "type": "string",
            "examples": [
              "0.0040000000"
            ]
          },
          "cost_usd_ticks": {
            "type": "integer",
            "examples": [
              40000000
            ]
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "request_id",
          "status",
          "query",
          "results",
          "filters",
          "answer",
          "related_queries",
          "usage"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ],
            "description": "Completed or failed, with nothing in between, as on Lineage. **Partial is not failure:** a search whose index answered and whose enrichment only half finished is a completed search. The shortfall is stated in `usage.results_enriched` and per result in `enrichment`."
          },
          "query": {
            "type": "string",
            "description": "The query as it was run."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "answer": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SearchAnswer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when the index had no direct answer."
          },
          "filters": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SearchFilters"
              },
              {
                "type": "null"
              }
            ],
            "description": "The scoping that was applied, with both `allowed_domains` and `blocked_domains` present (an unused one is an empty array), or null when none was. The only request field on this response, and it is here because the translation into `site:` operators is otherwise invisible: a filter that silently did nothing would look exactly like one that worked."
          },
          "related_queries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Follow-ups. Always an array, so a caller looping over suggestions never has to check whether the index bothered to send any."
          },
          "usage": {
            "$ref": "#/components/schemas/SearchUsage"
          }
        }
      },
      "Account": {
        "type": "object",
        "required": [
          "object",
          "balance"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "account"
            ]
          },
          "balance": {
            "type": "object",
            "required": [
              "usd_ticks",
              "usd",
              "input_tokens"
            ],
            "properties": {
              "usd_ticks": {
                "type": "integer",
                "description": "The authority. 1 USD = 10^10 ticks."
              },
              "usd": {
                "type": "string",
                "description": "The same number, for display.",
                "examples": [
                  "1.0000000000"
                ]
              },
              "input_tokens": {
                "type": "integer",
                "description": "What the balance buys at the Lineage input rate. 0 when prices cannot be read."
              }
            }
          }
        }
      },
      "BatchSubmission": {
        "type": "string",
        "description": "NDJSON. One `LineageRequest` per line. Up to 32 MB per submission."
      },
      "BatchJob": {
        "type": "object",
        "description": "The job as we report it. `id` is a handle of ours rather than the service's own id, so the id you get back is the one you can use again.",
        "required": [
          "id",
          "object",
          "status",
          "total"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The handle. Use it on every later call."
          },
          "object": {
            "type": "string",
            "enum": [
              "batch"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed"
            ],
            "description": "Always `queued` on the 202 from `POST /api/v1/batch`."
          },
          "total": {
            "type": "integer",
            "description": "Items in the submission."
          },
          "completed": {
            "type": "integer",
            "description": "Items finished. On `GET /api/v1/batch/{handle}` only."
          },
          "failed": {
            "type": "integer",
            "description": "Items that failed. On `GET /api/v1/batch/{handle}` only."
          }
        }
      }
    }
  }
}