> ## Documentation Index > Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt > Use this file to discover all available pages before exploring further. # Estimate a backfill, or run it with confirm > Without `confirm`, returns the estimate and does nothing. With `confirm: true`, starts a job. Backfills respect the namespace budget: an estimate that does not fit the remaining budget is refused (§6.9, §7.3.7). On a prefix path the backfill covers every namespace under the prefix, each within its own budget. ## OpenAPI ````yaml /api-reference/openapi.yaml post /namespaces/{ns}/judgments/{name}/backfill openapi: 3.1.0 info: title: Vainona API version: '1' license: name: Proprietary identifier: LicenseRef-Proprietary description: | The `/v1` contract from main spec §6. It is locked: changes within `/v1` are additive only, and anything breaking is `/v2`. - **Base URL.** `https://api.vainona.ai/v1`. - **Evolution.** Response objects may gain fields and enums may gain values. Clients must ignore what they do not know. Request objects reject unknown fields. - **Path segments.** Namespace names (`{ns}`) and document ids (`{id}`) may contain `/`. Send it percent-encoded as `%2F`, so that `acme/prod/tenant_123` is `acme%2Fprod%2Ftenant_123`. - **Templates (v1.5).** The judgment routes also take a namespace prefix ending in `/*`, such as `acme%2Fprod%2F*`. A judgment created there is a template: every namespace under the prefix inherits it, including ones created later. The most specific matching prefix wins (§7.7). - **Thresholds are settings (v1.5).** Named thresholds belong to the judgment, not to a version. They are evaluated at read time against the raw fields, so a change applies at once to every answer, with no recompute and no new version (§6.5). - **Entity judgments (entities, E1).** A judgment can read the documents that point at the judged one, through `context.related`, and apply only to documents matching `applies_to` (§6.5.2). Its answers carry a `watermark`, and creating one that runs `on_change` returns a replay estimate of its monthly cost until you confirm (§6.9). - **Referenced documents (entities, E3a).** A relation can also read the one document the judged document points at, through `join: {theirs: "id", mine: "attributes."}`. A change to what the relation renders of that document re-judges the judged documents that point at it and are inside `freshness.fanout.scope`: a fan-out. A large fan-out is a `fanout` job that waits for confirm (§6.5.2, §6.9). - **Idempotency.** Every write operation is idempotent by construction. `Idempotency-Key` is accepted on every mutating route and, while the node still caches the original response, returns it verbatim. - **Errors.** Every error is the `Error` envelope; the HTTP status follows the code (see each response). - **Rate limits.** Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `rate_limited` response adds `Retry-After`, except a daily allowance that is used up, which says when it renews in `details.resets_at` instead. - **Usage.** Every response that bills carries `usage`. Judging is billed in engine-neutral judgment units: one judgment answered, per started 1,000 tokens of its compiled context and its question together, at least 1 (§9). No response ever carries an engine's price. servers: - url: https://api.vainona.ai/v1 security: - apiKey: [] tags: - name: Namespaces description: Namespaces, their settings and cache warming (§6.2, §6.11). - name: Documents description: Writes, point reads and queries (§6.3 to §6.8). - name: Judgments description: >- Judgment definitions, versions, settings, activation, backfill and template detach (§6.5, §6.9, §7.7). - name: Outcomes and calibration description: | Post what actually happened to judged documents, and read how well answers match it: the calibration report, calibrated answers and threshold recommendations (§6.10). See [calibration](/concepts/calibration). - name: Jobs description: >- Backfill, shadow, periodic, deletion, reference index and fan-out jobs (§6.2, §6.9, §7.10.5). - name: Engines description: The engine registry (§6.5, §7.4.5). paths: /namespaces/{ns}/judgments/{name}/backfill: parameters: - $ref: '#/components/parameters/NamespaceOrTemplate' - $ref: '#/components/parameters/JudgmentName' post: tags: - Judgments summary: Estimate a backfill, or run it with confirm description: > Without `confirm`, returns the estimate and does nothing. With `confirm: true`, starts a job. Backfills respect the namespace budget: an estimate that does not fit the remaining budget is refused (§6.9, §7.3.7). On a prefix path the backfill covers every namespace under the prefix, each within its own budget. operationId: backfillJudgment parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BackfillRequest' responses: '200': description: The estimate, or the started job. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: oneOf: - $ref: '#/components/schemas/BackfillEstimate' - $ref: '#/components/schemas/JobStarted' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/BudgetExceeded' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/TooLarge' '422': $ref: '#/components/responses/EngineVersionUnavailable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: parameters: NamespaceOrTemplate: name: ns in: path required: true description: | A namespace name, or a template prefix ending in `/*` (§7.7), with any `/` sent as `%2F`: `acme%2Fprod%2Ftenant_123` or `acme%2Fprod%2F*`. schema: $ref: '#/components/schemas/NamespaceOrTemplate' JudgmentName: name: name in: path required: true schema: $ref: '#/components/schemas/Name' IdempotencyKey: name: Idempotency-Key in: header description: >- Returns the original response verbatim while the node still caches it. Correctness never depends on it. schema: type: string minLength: 1 schemas: BackfillRequest: type: object additionalProperties: false properties: filters: $ref: '#/components/schemas/Filter' confirm: type: boolean default: false BackfillEstimate: type: object required: - estimate properties: estimate: $ref: '#/components/schemas/Estimate' replay: $ref: '#/components/schemas/ReplayEstimate' description: >- Entities, E1 (§6.9). When the `PATCH` switches an entity judgment to `on_change`, what it would cost a month from then on, beside the backfill of the documents with no current answer. JobStarted: type: object required: - job_id properties: job_id: type: string NamespaceOrTemplate: type: string description: | A namespace name, or a template prefix: a namespace path ending in `/*`, such as `acme/prod/*`, which every namespace under `acme/prod/` inherits judgments from (§7.7). Up to 256 bytes. pattern: ^[A-Za-z0-9._:/-]+(/\*)?$ minLength: 1 maxLength: 256 Name: type: string description: >- A judgment, attribute or threshold name. Names are path segments in field references, so they never contain `.`. pattern: ^[A-Za-z0-9_-]+$ minLength: 1 maxLength: 128 Filter: description: | `[field, op, value]`, `["And" | "Or", [filters]]` or `["Not", filter]`. oneOf: - $ref: '#/components/schemas/EqualityFilter' - $ref: '#/components/schemas/RangeFilter' - $ref: '#/components/schemas/SetFilter' - $ref: '#/components/schemas/GlobFilter' - $ref: '#/components/schemas/ContainsFilter' - $ref: '#/components/schemas/ExistsFilter' - $ref: '#/components/schemas/AndOrFilter' - $ref: '#/components/schemas/NotFilter' Estimate: type: object required: - documents - tokens - judgment_units - cost_usd - duration_s properties: documents: type: integer format: int64 minimum: 0 tokens: type: integer format: int64 minimum: 0 judgment_units: type: integer format: int64 minimum: 0 description: >- Estimated judgment units (§9), from a sample of up to 1,000 documents. cost_usd: type: number minimum: 0 description: >- What the backfill is expected to cost you, the judgment units at the graduated prices of the tiers your organization will be in, counting what it has already used this month (§9). duration_s: type: integer format: int64 minimum: 0 description: >- Expected wall-clock seconds at the bulk pool's current share of the engine's rate limit. ReplayEstimate: type: object description: | Entities, E1 (§6.9). What an entity judgment would cost a month, from the namespace's last 30 days of writes run through its touch, debounce and ceiling rules. Storage keeps each document's newest version, so the replay sees each related document's creation, its newest write and the deletes still recorded: exact for documents written once, the last edit only for documents edited many times, when the figures are a lower bound (`lower_bound`). It does not credit dedup, which only lowers the bill. required: - replayed_days - entities - judgments_per_month - judgment_units_per_month - cost_usd_per_month - bulk_pool_share - lower_bound properties: replayed_days: type: integer minimum: 0 maximum: 30 description: >- Days of writes replayed, fewer than 30 in a younger namespace. The monthly figures are scaled from them to 30 days. entities: type: integer format: int64 minimum: 0 description: Documents the judgment applies to now. judgments_per_month: type: integer format: int64 minimum: 0 description: Evaluations the replay counted, scaled to 30 days. judgment_units_per_month: type: integer format: int64 minimum: 0 description: >- Judgment units (§9), from the mean compiled context and question of a sample of up to 1,000 entities. cost_usd_per_month: type: number minimum: 0 description: >- The units at the graduated prices of the tiers your organization will be in, counting what it has already used this month (§9). A confirmed request is refused with `budget_exceeded` when this is more than the namespace's monthly budget. bulk_pool_share: type: - number - 'null' minimum: 0 description: >- The share of the background judging rate available to this judgment that these evaluations would use, by requests or tokens, whichever is larger. Above 1, the judgment cannot keep up with the writes. Null for an engine without an account rate limit. lower_bound: type: boolean description: >- True when a related document in the replayed window has a `revision` higher than the writes the replay saw, so it was edited more often than the replay counted, and whenever `excludes` is present. The figures are then a lower bound, shown as "at least". The namespace budget still caps real spend. excludes: type: array description: | Entities, E3a (§6.9). What the figures leave out, present only when something is. `fanout`: the judgment has a relation that reads a referenced document, and the replay cannot count its fan-out, because storage keeps only a referenced document's newest version. Each fan-out above `fanout.job_above` shows its own estimate before it runs. minItems: 1 uniqueItems: true items: type: string enum: - fanout Error: type: object required: - error properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: type: object description: >- Code-specific detail, such as the scan estimate on a refused query. Every `internal` error has `request_id`. EqualityFilter: type: array prefixItems: - $ref: '#/components/schemas/FilterField' - enum: - Eq - NotEq - $ref: '#/components/schemas/FilterScalar' minItems: 3 items: false RangeFilter: type: array prefixItems: - $ref: '#/components/schemas/FilterField' - enum: - Lt - Lte - Gt - Gte - type: - string - number minItems: 3 items: false SetFilter: type: array prefixItems: - $ref: '#/components/schemas/FilterField' - enum: - In - NotIn - type: array minItems: 1 items: $ref: '#/components/schemas/FilterScalar' minItems: 3 items: false GlobFilter: type: array prefixItems: - $ref: '#/components/schemas/FilterField' - const: Glob - type: string minItems: 3 items: false ContainsFilter: type: array description: True when a string-array attribute contains the value. prefixItems: - $ref: '#/components/schemas/FilterField' - const: Contains - type: string minItems: 3 items: false ExistsFilter: type: array description: >- `["attributes.plan", "Exists", true]` matches documents that have the field; `false` matches those that do not. prefixItems: - $ref: '#/components/schemas/FilterField' - const: Exists - type: boolean minItems: 3 items: false AndOrFilter: type: array prefixItems: - enum: - And - Or - type: array minItems: 1 items: $ref: '#/components/schemas/Filter' minItems: 2 items: false NotFilter: type: array prefixItems: - const: Not - $ref: '#/components/schemas/Filter' minItems: 2 items: false ErrorCode: type: string description: | HTTP status by code: `invalid_request` 400, `unauthorized` 401, `budget_exceeded` 402, `forbidden` 403, `not_found` 404, `conflict` 409, `too_large` 413, `engine_version_unavailable` 422, `insufficient_labels` 422, `rate_limited` 429, `internal` 500, `engine_unavailable` 503. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - too_large - rate_limited - budget_exceeded - engine_unavailable - engine_version_unavailable - insufficient_labels - internal headers: RateLimitLimit: description: Requests allowed per second for this key. schema: type: integer minimum: 0 RateLimitRemaining: description: Requests left in the current window. schema: type: integer minimum: 0 RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 responses: InvalidRequest: description: '`invalid_request`: the request is malformed or breaks a rule of §6.' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: '`unauthorized`: the key is missing, unknown or revoked.' content: application/json: schema: $ref: '#/components/schemas/Error' BudgetExceeded: description: >- `budget_exceeded`: the namespace is over its monthly compute budget, or the estimate does not fit it. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: '`forbidden`: the key''s role or namespace prefix does not allow this.' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: '`not_found`: the namespace, document, judgment or job does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- `conflict`: the namespace is being deleted, an object a read needs was compacted away and the read (or the query, without its cursor) must restart (§7.5.11), or the judgment is inherited from a template and this namespace cannot create, activate or delete it (§7.7). content: application/json: schema: $ref: '#/components/schemas/Error' TooLarge: description: >- `too_large`: the request body (on any route), a document, or the estimated query scan is over its limit. `details` carries the estimate for queries. It also answers a write that would take `default/quickstart` past its size cap (10,000 documents or 100 MB), with `details.max_documents` and `details.max_bytes`. content: application/json: schema: $ref: '#/components/schemas/Error' EngineVersionUnavailable: description: >- `engine_version_unavailable`: the engine version is not active in the registry. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- `rate_limited`: slow down. `Retry-After` says for how long, except when a daily allowance is used up: then `details.resets_at` says when it renews, and there is no `Retry-After`. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' Internal: description: >- `internal`: something failed on our side. Nothing partial is returned, and a request never commits part of itself. Most `internal` errors committed nothing. A write can instead fail with a message saying it may have been committed, when we could not tell whether its batch landed (§7.2.10): it then committed all of it or none of it. Retrying a write is safe either way, because writes are idempotent. The message is generic and carries a request id, also in `details.request_id`, which support uses to find the cause. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: | An organization API key. Keys carry a role (`read_write` or `read_only`) and may be restricted to a namespace prefix such as `acme/*`, or to one namespace such as `acme/prod/tenant_1`. A prefix matches on a `/` boundary: `acme/prod/tenant_1*` covers `acme/prod/tenant_1` and everything under `acme/prod/tenant_1/`, never `acme/prod/tenant_12`. ````