> ## Documentation Index > Fetch the complete documentation index at: https://docs.brussle.com/llms.txt > Use this file to discover all available pages before exploring further. # Run this month's recipe tuning now > Starts this month's recipe-tuning run of the active version, or returns it: one run per version, engine epoch and calendar month (UTC), whether this or the nightly calibration starts it. The response is the suggestion as it stands, `running` until the run ends. Runs are never billed. On a template prefix, the template's judgment, on its tenants' pooled outcomes. `invalid_request` when the version cannot be tuned: a judgment the namespace inherits from a template, a composite, no context recipe, a recipe with nothing to make smaller, or no calibration fit yet (100 outcomes, 20 of each kind). On the Team plan and above: below it, `plan_required`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /namespaces/{ns}/judgments/{name}/recipe-tuning openapi: 3.1.0 info: title: Brussle API version: '1' license: name: Proprietary identifier: LicenseRef-Proprietary description: | The `/v1` contract. It is locked: changes within `/v1` are additive only, and anything breaking is `/v2`. - **Base URL.** `https://api.brussle.com/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.** 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. - **Thresholds are settings.** 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. - **Entity judgments.** A judgment can read the documents that point at the judged one, through `context.related`, and apply only to documents matching `applies_to`. Its answers carry a `watermark`, and creating one that runs `on_change` returns a replay estimate of its monthly cost until you confirm. - **Referenced documents.** 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 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. Groups keep aggregates per key value for reporting. - **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. Every request that changes something also takes an `Idempotency-Key`, so that creates, activations, backfills, draws and the rest can be retried safely too: a retry with the key gets the first response back, verbatim and marked `Idempotent-Replayed: true`, instead of running again (see the parameter). - **Errors.** Every error is the `Error` envelope; the HTTP status follows the code (see each response). - **Rate limits.** Every response to a request whose key was accepted carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, which count the key's requests a second; a request refused before its key is checked (`unauthorized`, or a route that does not exist) carries neither. 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. Every `503` carries `Retry-After` too. Reads of one namespace also have a concurrency limit: past 32 gets and queries in flight at once, one more is `rate_limited` with `Retry-After` and `details.concurrent_reads`, whatever the rate-limit headers show. - **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). No response ever carries an engine's price. servers: - url: https://api.brussle.com/v1 security: - apiKey: [] tags: - name: Namespaces description: Namespaces, their settings and cache warming. - name: Documents description: Writes, point reads and queries. - name: Judgments description: >- Judgment definitions, versions, settings, activation, backfill and template detach. - 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. See [calibration](/concepts/calibration). - name: Groups description: > Groups keep aggregates per value of a key attribute, a group-by you declare 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, resync, group build, discovery and simulation jobs. - name: Engines description: The engine registry. - name: Organization description: | Settings of the whole organization: prefixes marked non-production, which the tenant fee and template calibration pools leave out. - name: Subscriptions description: | Saved queries that send an event when a document starts or stops matching: the query's filter grammar, 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. paths: /namespaces/{ns}/judgments/{name}/recipe-tuning: parameters: - $ref: '#/components/parameters/NamespaceOrTemplate' - $ref: '#/components/parameters/JudgmentName' post: tags: - Outcomes and calibration summary: Run this month's recipe tuning now description: | Starts this month's recipe-tuning run of the active version, or returns it: one run per version, engine epoch and calendar month (UTC), whether this or the nightly calibration starts it. The response is the suggestion as it stands, `running` until the run ends. Runs are never billed. On a template prefix, the template's judgment, on its tenants' pooled outcomes. `invalid_request` when the version cannot be tuned: a judgment the namespace inherits from a template, a composite, no context recipe, a recipe with nothing to make smaller, or no calibration fit yet (100 outcomes, 20 of each kind). On the Team plan and above: below it, `plan_required`. operationId: tuneRecipe parameters: - $ref: '#/components/parameters/IdempotencyKey' responses: '202': description: The run started, is running, or ended this month. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/RecipeSuggestion' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PlanRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '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 `/*`, 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: | One key per logical request, reused only on its retries. A key belongs to one request: within your organization, the same method, path, query and body. For 24 hours after a successful response, a request with the key and the same body gets that response back verbatim, with `Idempotent-Replayed: true`, and runs nothing. Only a successful response is kept, so the retry of a request that failed runs again. While the first request runs or its response is kept, the key with a different request is `idempotency_key_reused` (422). A request sent while one with its key is still running is `rate_limited` with `Retry-After: 1`, without running: retry it to get the first one's response. In the rare case the key can't be checked, the request runs as if it had none. schema: type: string minLength: 1 maxLength: 255 headers: RateLimitLimit: description: >- Requests allowed per second for this key. Only on responses to a request whose key was accepted. schema: type: integer minimum: 0 RateLimitRemaining: description: >- Requests left in the current one-second window for this key. It does not count the per-namespace limit on reads in flight. schema: type: integer minimum: 0 RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 schemas: RecipeSuggestion: type: object description: | The cheaper context recipe a version's outcomes support, from its last recipe-tuning run, or why there is none. required: - version - status - reason - message - headline - suggestion - computed_at - next_run_after - plan_required properties: version: $ref: '#/components/schemas/JudgmentVersionNumber' status: type: string enum: - not_run - running - ready - none description: | - `not_run`: no run yet; `reason` says why. - `running`: a run is testing smaller recipes. - `ready`: `suggestion` holds a cheaper recipe. - `none`: the last run found none; `reason` says why. reason: description: | Why there is no suggestion. Not run: `awaiting_run` (the next calibration run starts it), `too_few_outcomes` (no calibration fit yet), `no_recipe`, `no_smaller_recipe` (nothing to drop or halve, such as a single field), `composite`, `inherited` (the template has the suggestion). None: `nothing_to_save` (every answer is already standard, the smallest size class), `no_cheaper_recipe` (nothing moves enough answers to a smaller size class to be meaningfully cheaper), `accuracy_would_drop`, `too_few_outcomes`, `cost_cap` (the run stopped at this month's limit) or `superseded` (the engine's model changed during the run). Null while running and when ready. oneOf: - type: string enum: - awaiting_run - too_few_outcomes - no_recipe - composite - inherited - nothing_to_save - no_smaller_recipe - no_cheaper_recipe - accuracy_would_drop - cost_cap - superseded - type: 'null' message: type: string description: What `status` and `reason` mean, in a sentence. headline: type: - string - 'null' description: >- One sentence when ready, such as "A context recipe 42% cheaper per answer, with accuracy unchanged within noise on 312 labelled answers." suggestion: oneOf: - $ref: '#/components/schemas/RecipeSuggestionDetail' - type: 'null' computed_at: description: When the last run ended. Null before one has. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' next_run_after: description: >- The earliest the nightly calibration starts the next run, 30 days after the last started. Null before one has. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' plan_required: description: Set below Team, where the recipe itself is withheld. oneOf: - $ref: '#/components/schemas/RecipePlanRequired' - type: 'null' 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. Up to 256 bytes. Never exactly `.` or `..`, which a URL path can't carry. 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 JudgmentVersionNumber: type: integer format: int32 minimum: 1 RecipeSuggestionDetail: type: object description: | One smaller recipe, measured against the current one on the same labelled answers and engine epoch. Apply it by posting `definition` as a new version and activating it through its shadow report. required: - recipe - removed - definition - unit_reduction - cost_per_answer_before - cost_per_answer_after - held_out - labels - engine_version - computed_at properties: recipe: description: The whole new context recipe. Null below Team. oneOf: - $ref: '#/components/schemas/ContextRecipe' - type: 'null' removed: description: >- What changed, in words, such as "the field state.internal_notes". Null below Team. oneOf: - type: array items: type: string - type: 'null' definition: description: >- The exact body to `POST /namespaces/{ns}/judgments`, the active version's definition with only `context` changed. It gives no `thresholds`, so the judgment's current thresholds carry over when the new version is activated. Null below Team. oneOf: - $ref: '#/components/schemas/CreateJudgmentFromDefinition' - type: 'null' unit_reduction: type: number minimum: 0.2 maximum: 1 description: >- The share of judgments per answer it saves, counted by size class, at least 0.2. cost_per_answer_before: type: number minimum: 0 description: >- Mean judgments per answer, counted by size class, with the current recipe, on the labelled answers. cost_per_answer_after: type: number minimum: 0 description: The same with this recipe. held_out: $ref: '#/components/schemas/RecipeHeldOut' labels: type: integer format: int64 minimum: 100 description: The labelled answers both recipes were scored on. engine_version: type: string description: >- The engine epoch both were judged in, that of the version's calibration fit. computed_at: $ref: '#/components/schemas/Timestamp' Timestamp: type: string format: date-time description: RFC 3339, UTC. RecipePlanRequired: type: object description: Why the recipe itself is withheld, as `plan_required` says it. required: - message - capability - required_plan - plan properties: message: type: string capability: type: string enum: - recipe_tuning required_plan: type: string enum: - team - scale plan: type: string enum: - developer - team - scale 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: reason: type: string description: > Why, where one code has more than one cause. On `forbidden`, `payment_overdue`: a payment has been unpaid for 14 days, so the organization's keys are read-only until it is paid; reads still work, and paying restores writes within a few minutes. A key that is read-only itself is `forbidden` without a `reason`. On the events feed's `invalid_request`, `cursor_expired`. suggested_context: description: >- On a create without a context recipe, the recipe suggested from the namespace's documents, or null when there are none. oneOf: - $ref: '#/components/schemas/SuggestedContext' - type: 'null' 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`; 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: > Up to 4 relations, by name: documents in the same namespace that point at the judged one, or 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' previous: $ref: '#/components/schemas/PreviousRecipe' CreateJudgmentFromDefinition: type: object description: >- A definition plus, for the name's first version, the judgment's freshness settings. allOf: - $ref: '#/components/schemas/JudgmentDefinition' properties: freshness: $ref: '#/components/schemas/FreshnessSettings' activate: type: boolean description: >- Activate this version on creation. In v1 this implies `force`. Refused for a composite judgment, which activation fits on your labels first. confirm: type: boolean default: false description: > Required to create a version with `context.related` on a judgment whose policy will be `on_change`. Without it, the response is the replay estimate of the monthly cost, and nothing is created; for a judgment that can fan out it also carries `fanout`, the rolling limit the confirm sets. Ignored for other judgments. use_context: type: string enum: - suggested - whole_state description: | Instead of `context`: `suggested` creates with the recipe suggested from a sample of the namespace's documents, the one a create without `context` returns in `details.suggested_context`; `whole_state` sends the whole `state`, with a warning. Refused together with `context`. dry_run: $ref: '#/components/schemas/DryRunFlag' unevaluatedProperties: false RecipeHeldOut: type: object description: | Both recipes scored the way a calibration fit is judged: each outcome read with a fit made without it. required: - log_loss_before - log_loss_after - accuracy_before - accuracy_after - interval properties: log_loss_before: type: number minimum: 0 log_loss_after: type: number minimum: 0 accuracy_before: type: number minimum: 0 maximum: 1 accuracy_after: type: number minimum: 0 maximum: 1 interval: $ref: '#/components/schemas/LiftInterval' description: >- The 95% interval of the change in log loss, after minus before; above 0 is worse. 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, `idempotency_key_reused` 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 - idempotency_key_reused - internal SuggestedContext: type: object description: | The recipe suggested for a create without `context`, in the refusal's `details.suggested_context`. From a sample of the documents the definition applies to: it keeps short text, numbers, booleans and small attributes, and leaves out ids, timestamps, links, binary-looking and very long values, and rarely present fields; `excluded` says why for each. `max_tokens` is set to keep the context in the standard size class, 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, less the question's tokens, so a context that fills it stays standard with its question. 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 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]$ Relation: type: object description: | 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. 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`. 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 (up to the `options.from` candidate limit 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 at most the `options.from` candidate limit (see Limits) 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. An entry may be a `BandedField`, which renders a number as its band. An entry may also be a plain judgment's `answers..value` and `answers..thresholds.` as they are, and its `.p`, `.score` and `.dist.