> ## 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. # Add aggregates or change keep_keys > `aggregate` adds to the group's aggregates (existing ones never change meaning, and cannot be removed while a judgment reads them); it starts a `group_build` job for the new ones. When judgments read the group, adding one would move their projections, so without `confirm: true` it returns their estimate and changes nothing. `keep_keys` needs no confirm. A namespace cannot change a group it inherits (`conflict`). ## OpenAPI ````yaml /api-reference/openapi.yaml patch /namespaces/{ns}/groups/{name} 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. - **Relations.** A relation can read plain judgments' answers (banded or cut, never summed), or be a blocking relation over the documents that share a key, which a `choice` can choose among with `options.from`. A recipe can read the document's groups (`context.group`) and the document as the judgment last saw it (`context.previous`). A judgment that can fan out confirms its rolling limits once, at create; past them, work is deferred, reads `stale` with an event, and catches up on its own. Nothing waits for a confirm at runtime (§6.5.2, §6.5.3, §6.9). The E3a settings this retires (`job_above`, `confirm_jobs`, `auto_daily_limit`, `fanout` jobs) are marked `deprecated` here until servers stop returning them; requests that set them are refused. - **Idempotency.** Every write operation is idempotent by construction: a retried append adds nothing while its values are still in the array, and a retried upsert or patch sets the same content again (§6.4). `Idempotency-Key` is accepted on the mutating routes that declare it and, while the node still caches the original response, returns it verbatim. Marking or unmarking a non-production prefix, and starting this month's recipe-tuning run, change nothing when repeated, so they take none. - **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 per judgment, engine-neutral, by size class: one judgment answered counts by the tokens of its compiled context and its question together, 1 if standard (up to 2,000 tokens), 4 if large (up to 8,000) and 16 if extra-large (up to 32,000, the engine maximum) (§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: Groups description: | Relations (§6.5.3, §7.7). Groups keep aggregates per value of a key attribute, for judgments to read as the population a document belongs to and for reporting; a template's tenant summary publishes each tenant's groups, banded, as a document the platform can judge. - name: Jobs description: >- Backfill, shadow, periodic, deletion, reference index, evaluation export, and from relations resync, group build, discovery and simulation jobs (§6.2, §6.9, §7.10.5). - name: Engines description: The engine registry (§6.5, §7.4.5). - name: Organization description: | Settings of the whole organization: prefixes marked non-production, which the tenant fee and template calibration pools leave out (§9). - name: Subscriptions description: | Saved queries that send an event when a document starts or stops matching: the query's filter grammar (§6.8), on a namespace or a template prefix, with the fields each event carries. - name: Webhooks description: | Webhook endpoints, the events feed, the delivery log, redelivery and recovery. Every event type and its body is under `webhooks`. Events are delivered at least once, signed as Standard Webhooks, and kept for 30 days. Webhooks are on every plan, and deliveries are not billed; plans set how many endpoints an organization has (§9). paths: /namespaces/{ns}/groups/{name}: parameters: - $ref: '#/components/parameters/NamespaceOrTemplate' - $ref: '#/components/parameters/GroupName' patch: tags: - Groups summary: Add aggregates or change keep_keys description: | `aggregate` adds to the group's aggregates (existing ones never change meaning, and cannot be removed while a judgment reads them); it starts a `group_build` job for the new ones. When judgments read the group, adding one would move their projections, so without `confirm: true` it returns their estimate and changes nothing. `keep_keys` needs no confirm. A namespace cannot change a group it inherits (`conflict`). operationId: updateGroup parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateGroupRequest' responses: '200': description: >- The group with the change applied, or the readers' estimate when it needs `confirm`. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Group' - $ref: '#/components/schemas/DownstreamEstimate' '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' '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' GroupName: 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: UpdateGroupRequest: type: object description: At least one of `aggregate` and `keep_keys`. additionalProperties: false minProperties: 1 properties: aggregate: $ref: '#/components/schemas/GroupAggregate' description: Aggregates to add. Existing ones stay as they are. keep_keys: $ref: '#/components/schemas/Duration' confirm: type: boolean default: false description: >- Required to add an aggregate when judgments read the group; without it, the response is their estimate. Group: type: object description: >- Relations (§6.5.3). A group, its status and, on get in a namespace, its rows. required: - name - key - aggregate - keep_keys - status - created_at properties: name: $ref: '#/components/schemas/Name' key: type: string pattern: ^attributes\.[A-Za-z0-9_-]+$ match: $ref: '#/components/schemas/AttributeFilter' aggregate: $ref: '#/components/schemas/GroupAggregate' keep_keys: $ref: '#/components/schemas/Duration' template: $ref: '#/components/schemas/NamespaceOrTemplate' description: >- Present when the group is inherited, the template prefix it comes from. status: type: string description: >- `building` until its `group_build` job has computed the aggregates, then `ready`. Judgments that read it wait for it. enum: - building - ready job_id: type: - string - 'null' description: The `group_build` job, while it runs. readers: type: array description: >- The judgments that read the group. Deleting it is `conflict` while there are any. items: $ref: '#/components/schemas/Name' live_keys: type: - integer - 'null' minimum: 0 description: Live key values now; null on a template's prefix path. warnings: type: array description: >- `group_over_cap`: more than 1,000 live key values, so its readers read `stale` (`group_over_cap`) until key values age out past `keep_keys`. items: type: string enum: - group_over_cap as_of: description: >- The `seq` of the merge the rows are exact at. Absent from lists and on a template's prefix path. oneOf: - $ref: '#/components/schemas/Revision' - type: 'null' rows: description: >- On get in a namespace, one row per live key value, the largest `count` first. Null on a template's prefix path, absent from lists. oneOf: - type: array maxItems: 1000 items: $ref: '#/components/schemas/GroupRow' - type: 'null' created_at: $ref: '#/components/schemas/Timestamp' DownstreamEstimate: type: object description: | Relations. A change that moves what other judgments read, sent without `confirm`: a threshold readers' relations name (§6.9), an aggregate added to a group judgments read (§6.5.3), or a tenant summary's groups or bands (§7.7). Nothing changed. Send it again with `confirm: true`. required: - downstream not: description: >- An applied change is `JudgmentSettingsApplied`, even with `downstream`. required: - judgment properties: downstream: type: array items: $ref: '#/components/schemas/DownstreamLine' 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 GroupAggregate: type: object description: | Relations (§6.5.3). What the group keeps per key value, over the documents matching `match`, exact as of the last merge. At most 8 paths in total. `quantiles` keeps a mergeable sketch per path, which `position` reads and `GET` reports as p50, p90 and p99. `count_where` counts documents by plain judgments' answers, with the roll-up rules; `sum` and `avg` over answers are `invalid_request`. additionalProperties: false minProperties: 1 properties: count: const: true description: How many live documents match. count_where: $ref: '#/components/schemas/CountWhere' sum: $ref: '#/components/schemas/AggregatePaths' avg: $ref: '#/components/schemas/AggregatePaths' min: $ref: '#/components/schemas/AggregatePaths' max: $ref: '#/components/schemas/AggregatePaths' quantiles: $ref: '#/components/schemas/AggregatePaths' Duration: type: string description: A whole number and a unit (`s`, `m`, `h` or `d`), such as `7d` or `1h`. pattern: ^[1-9][0-9]*[smhd]$ AttributeFilter: type: object description: | Entities, E1 (§6.5). Which documents something applies to, by their attributes. Each key is an attribute path; a value is equality, and a list of values is `In`, as in query filters. Keys combine with `And`. minProperties: 1 maxProperties: 8 propertyNames: type: string pattern: ^attributes\.[A-Za-z0-9_-]+$ additionalProperties: oneOf: - $ref: '#/components/schemas/AttributeFilterValue' - type: array minItems: 1 items: $ref: '#/components/schemas/AttributeFilterValue' Revision: type: integer format: int64 minimum: 0 GroupRow: type: object description: >- The merged aggregates of one key value, keyed as a judgment's `context.group.fields` names them, such as `count` or `avg(state.tickets_30d)`; a quantiles path gives `p50(...)`, `p90(...)` and `p99(...)`. Null where no live document has a number. required: - key - values properties: key: $ref: '#/components/schemas/AttributeFilterValue' values: type: object additionalProperties: type: - number - 'null' Timestamp: type: string format: date-time description: RFC 3339, UTC. DownstreamLine: type: object description: | Relations (§6.9). One reader's cost of a change to a judgment whose answers its relations read: the re-judgments the change would cause a month (for a one-off such as a backfill, in the month it runs), counted from the answer history's band and cut flips over the last 30 days, priced by the reader's size class at your tiers. required: - judgment - judgments_per_month - cost_usd properties: judgment: $ref: '#/components/schemas/Name' judgments_per_month: type: integer format: int64 minimum: 0 cost_usd: type: number minimum: 0 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`. properties: suggested_context: description: >- On a create without a context recipe, the recipe suggested from the namespace's documents, or null when there are none (D-v15-612). oneOf: - $ref: '#/components/schemas/SuggestedContext' - type: 'null' CountWhere: type: object description: | Relations (§6.5.2). How many selected documents match every key: a plain judgment's `answers..value` or `answers..thresholds.` by equality (a list is `In`), or its `.p` or `.score` by an inline cut. Rendered as `count_where`. minProperties: 1 maxProperties: 8 propertyNames: type: string pattern: ^answers\.[A-Za-z0-9_-]+\.(value|p|score|thresholds\.[A-Za-z0-9_-]+)$ additionalProperties: oneOf: - $ref: '#/components/schemas/AttributeFilterValue' - type: array minItems: 1 items: $ref: '#/components/schemas/AttributeFilterValue' - $ref: '#/components/schemas/AnswerCut' AggregatePaths: type: array minItems: 1 maxItems: 8 uniqueItems: true items: type: string description: A `state` or `attributes` path. Keys in it cannot contain `(` or `)`. pattern: ^(state|attributes)(\.[^.()]+)+$ AttributeFilterValue: type: - string - number - boolean ErrorCode: type: string description: | HTTP status by code: `invalid_request` 400, `unauthorized` 401, `budget_exceeded` 402, `plan_required` 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, `unavailable` 503. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - too_large - rate_limited - budget_exceeded - plan_required - engine_unavailable - engine_version_unavailable - unavailable - insufficient_labels - internal SuggestedContext: type: object description: | The recipe suggested for a create without `context` (D-v15-612), in the refusal's `details.suggested_context`. From up to 100 of the documents the definition applies to: short text fields, numbers and small attributes are kept; ids, timestamps, URLs, base64 and long values are left out; arrays longer than 5 keep their last 5; and `max_tokens` caps the largest context at a multiple of 500, at most 2,000. The same documents always give the same recipe. required: - recipe - cost_per_answer - whole_state_cost_per_answer - sampled_documents - excluded properties: recipe: $ref: '#/components/schemas/ContextRecipe' cost_per_answer: type: - number - 'null' minimum: 0 description: >- Mean judgments per answer, counted by size class, over the sample with this recipe and the definition's question. The suggested `max_tokens` is at most 2,000, the standard ceiling, which keeps the context standard; the question counts too, so a long one can make an answer large. whole_state_cost_per_answer: type: - number - 'null' minimum: 0 description: The same with the whole `state`. sampled_documents: type: integer minimum: 1 excluded: type: array description: >- Each path left out, and why, so you can put back what the question needs. items: type: object required: - path - reason properties: path: type: string reason: type: string enum: - id - timestamp - url - binary - long - rare - too_many AnswerCut: type: object description: >- Relations (§6.5.2). An inline cut on an answer's `p` or `score`, exactly as stable as a named threshold. One bound. additionalProperties: false minProperties: 1 maxProperties: 1 properties: gte: type: number gt: type: number lte: type: number lt: type: number ContextRecipe: type: object description: | What the engine sees. A create without it is refused with a suggested recipe, unless `use_context` asks for the suggestion or the whole `state` (D-v15-612); a version with no recipe sends the whole `state`, subject to the engine limit. additionalProperties: false properties: fields: type: array description: Paths included verbatim, in order. items: type: string pattern: ^(state|attributes)(\.[^.]+)+$ last_n: type: object description: Per array path, keep the last n elements. additionalProperties: type: integer minimum: 1 window: type: object description: >- Per array path whose elements have a timestamp field `at`, keep elements within the window. additionalProperties: $ref: '#/components/schemas/Duration' max_tokens: type: integer minimum: 1 description: Hard cap; the compiler truncates from the end of the last field. related: type: object description: | Entities, E1 (§6.5.2). Up to 4 relations, by name: documents in the same namespace that point at the judged one or, from E3a, the one document it points at. Each renders as a `related.` entry after `fields`, and a write that changes what it renders makes the judged document's answer `pending` until it is judged again (for a referenced document, only inside the re-judge scope; outside it, the answer is `stale` with `stale_reason` `referenced_changed`). minProperties: 1 maxProperties: 4 propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Relation' group: type: object description: | Relations (§6.5.3). Up to 4 groups of the namespace, by name: the aggregates of the judged document's key value, banded, and the document's own position in them. Each renders as a `group.` entry after `related`. A crossing of a band re-judges the key value's members, within the judgment's `freshness.fanout.crossings_per_month`. minProperties: 1 maxProperties: 4 propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/GroupRead' previous: $ref: '#/components/schemas/PreviousRecipe' Relation: type: object description: | Entities, E1 (§6.5.2). Documents that point at the judged document. They are ordered newest `created_at` first: `window` keeps those created within the window, then `last_n` keeps the newest n. At least one of `last_n` and `window` is required, and at least one of `fields` and `aggregate`. A relation reads at most the newest 1,000 documents. Entities, E3a: with `join: {theirs: "id", mine: "attributes."}` the relation reads the one document the judged document points at, its referenced document, and takes neither `last_n` nor `window`. Relations: with `join: {theirs: "attributes.", mine: "attributes."}` it is a blocking relation over the documents that share the judged document's key value. It needs `window`, takes `last_n` up to 254 (50 when a `choice` chooses among it with `options.from`), and a change to its block re-judges the block's judged documents. `fields`, `aggregate` and `match` may read plain judgments' answers (`answers..`), banded or cut. additionalProperties: false required: - match - join allOf: - description: A relation renders fields or aggregates. if: not: required: - fields then: required: - aggregate - description: >- A relation over the documents that point at the judged one is bounded by `last_n` or `window`. if: properties: join: type: object properties: mine: const: id then: anyOf: - required: - last_n - required: - window - description: >- A relation that reads the referenced document takes neither `last_n` nor `window`. if: properties: join: type: object properties: theirs: const: id then: not: anyOf: - required: - last_n - required: - window - description: A blocking relation needs `window`, and reads at most 254 documents. if: properties: join: $ref: '#/components/schemas/BlockingJoin' then: required: - window properties: last_n: type: integer maximum: 254 properties: match: $ref: '#/components/schemas/RelationMatch' description: Which documents the relation reads. join: $ref: '#/components/schemas/RelationJoin' last_n: type: integer minimum: 1 maximum: 1000 description: >- Keep the newest n. Not on a relation that reads a referenced document; at most 254 on a blocking relation, and 50 when `options.from` chooses among it. window: $ref: '#/components/schemas/Duration' description: >- Keep documents created within this long before the later of the judged document's newest write and its newest related creation, at the answer's watermark. An edit to an old related document never moves the window. Not on a relation that reads a referenced document. fields: type: array description: >- Paths to include from each document, rendered under `records`, newest first. From entities E3a, an entry may be a `BandedField`, which renders a number as its band. From relations, a plain judgment's `answers..value` and `answers..thresholds.` as they are, and its `.p`, `.score` and `.dist.