> ## 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. # List active engine versions > Active engine versions with their limits and conformance results (§7.4.5, §7.4.6). Never prices; judging is billed in judgment units whichever engine answers (§9). ## OpenAPI ````yaml /api-reference/openapi.yaml get /engines 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: /engines: get: tags: - Engines summary: List active engine versions description: >- Active engine versions with their limits and conformance results (§7.4.5, §7.4.6). Never prices; judging is billed in judgment units whichever engine answers (§9). operationId: listEngines responses: '200': description: The engine registry. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/EngineList' '401': $ref: '#/components/responses/Unauthorized' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: 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 schemas: EngineList: type: object required: - engines properties: engines: type: array items: $ref: '#/components/schemas/Engine' Engine: type: object description: An engine version and its limits. It never carries a price (§6.2). required: - name - version - status - limits - probe properties: name: type: string version: type: string status: type: string enum: - active - deprecated - unavailable limits: type: object required: - context_tokens - max_choice_options - score_levels - questions_per_request properties: context_tokens: type: integer minimum: 1 description: Tokens for state plus the longest question. max_choice_options: type: integer minimum: 2 description: Including the escape option. score_levels: type: object required: - min - max properties: min: type: integer minimum: 2 max: type: integer minimum: 2 questions_per_request: type: integer minimum: 1 conformance: oneOf: - $ref: '#/components/schemas/ConformanceResult' - type: 'null' probe: type: object description: The latest health probe of this version (§7.4.3). required: - status - checked_at properties: status: type: string enum: - unknown - ok - failing checked_at: description: Null before the first probe. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' 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`. ConformanceResult: type: object description: The conformance suite run that made this version active (§7.4.6). required: - golden_set - run_at - bool - choice - score properties: golden_set: type: string examples: - golden-v1 run_at: $ref: '#/components/schemas/Timestamp' bool: $ref: '#/components/schemas/ConformanceMetrics' choice: $ref: '#/components/schemas/ConformanceMetrics' score: $ref: '#/components/schemas/ConformanceMetrics' latency_ms: type: object properties: batch_1: $ref: '#/components/schemas/LatencyPercentiles' batch_32: $ref: '#/components/schemas/LatencyPercentiles' Timestamp: type: string format: date-time description: RFC 3339, UTC. 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 ConformanceMetrics: type: object required: - accuracy - expected_calibration_error - log_loss properties: accuracy: $ref: '#/components/schemas/Probability' expected_calibration_error: type: number minimum: 0 log_loss: type: number minimum: 0 option_order_flip_rate: $ref: '#/components/schemas/Probability' description: Choice only. Share of answers that flip when options are re-ordered. LatencyPercentiles: type: object required: - p50 - p90 properties: p50: type: number minimum: 0 p90: type: number minimum: 0 Probability: type: number minimum: 0 maximum: 1 responses: Unauthorized: description: '`unauthorized`: the key is missing, unknown or revoked.' 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' 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`. ````