> ## 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. # Change a subscription's events, include, endpoint or bulk > Changes `events`, `include`, `endpoint` and `bulk`, from the next event on. `filters` never changes (`invalid_request`): a different filter has no honest edges, so create a new subscription and delete this one. A namespace cannot change a subscription it inherits (`conflict`); change it on the template's prefix path, which needs templates (`plan_required` below Team). A new `include` or `endpoint` is checked as on create. ## OpenAPI ````yaml /api-reference/openapi.yaml patch /namespaces/{ns}/subscriptions/{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. 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: 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 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, fan-out and evaluation export 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}/subscriptions/{name}: parameters: - $ref: '#/components/parameters/NamespaceOrTemplate' - $ref: '#/components/parameters/SubscriptionName' patch: tags: - Subscriptions summary: Change a subscription's events, include, endpoint or bulk description: | Changes `events`, `include`, `endpoint` and `bulk`, from the next event on. `filters` never changes (`invalid_request`): a different filter has no honest edges, so create a new subscription and delete this one. A namespace cannot change a subscription it inherits (`conflict`); change it on the template's prefix path, which needs templates (`plan_required` below Team). A new `include` or `endpoint` is checked as on create. operationId: updateSubscription parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' responses: '200': description: The subscription as changed. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/Subscription' '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' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' '503': $ref: '#/components/responses/Unavailable' 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' SubscriptionName: 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: UpdateSubscriptionRequest: type: object description: >- Every key is optional; the others keep their values. `filters` never changes. additionalProperties: false minProperties: 1 properties: events: type: array minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/SubscriptionEventKind' include: $ref: '#/components/schemas/SubscriptionInclude' endpoint: description: Null sends the events to the feed only. oneOf: - $ref: '#/components/schemas/WebhookEndpointId' - type: 'null' bulk: $ref: '#/components/schemas/SubscriptionBulk' Subscription: type: object required: - id - name - filters - events - include - endpoint - bulk - status - live_at - lag_ms - warnings - created_at properties: id: $ref: '#/components/schemas/SubscriptionId' name: $ref: '#/components/schemas/Name' template: $ref: '#/components/schemas/TemplateName' description: >- Present when the subscription is inherited, the template prefix it comes from, such as `acme/prod/*`. filters: $ref: '#/components/schemas/Filter' events: type: array items: $ref: '#/components/schemas/SubscriptionEventKind' include: $ref: '#/components/schemas/SubscriptionInclude' endpoint: oneOf: - $ref: '#/components/schemas/WebhookEndpointId' - type: 'null' bulk: $ref: '#/components/schemas/SubscriptionBulk' status: description: >- In this namespace. Null on a template's prefix path, where each namespace syncs on its first change after the subscription exists. oneOf: - $ref: '#/components/schemas/SubscriptionStatus' - type: 'null' live_at: description: When the subscription went `live` in this namespace. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' lag_ms: type: - integer - 'null' format: int64 minimum: 0 description: >- How long the oldest change the subscription has not evaluated yet has waited, in milliseconds; 0 when it is up to date. A quiet subscription records its progress about once a minute, so a change counts only once it has waited longer than that. Null while syncing and on a template's prefix path. warnings: type: array items: $ref: '#/components/schemas/SubscriptionWarning' created_at: $ref: '#/components/schemas/Timestamp' 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 SubscriptionEventKind: type: string description: >- `entered` when a document starts matching; `exited` when it stops matching or is deleted. enum: - entered - exited SubscriptionInclude: type: object description: | The attributes and answers each event carries. The fields the filter reads are always included, and `state` never is. At most 24 fields in all, counting those the filter reads. An `on_read` judgment is refused. additionalProperties: false properties: attributes: type: array uniqueItems: true maxItems: 24 items: $ref: '#/components/schemas/Name' answers: type: array uniqueItems: true maxItems: 24 items: $ref: '#/components/schemas/Name' WebhookEndpointId: type: string pattern: ^we_[0-9a-z]{26}$ SubscriptionBulk: type: string description: | What bulk changes send: a backfill, the first sync, or a resync after a threshold edit, an activation or new composite weights. `summary` updates membership silently and sends one `subscription.synced`. `deliver` sends every transition, with its `cause`. enum: - summary - deliver default: summary SubscriptionId: type: string pattern: ^sub_[0-9a-z]{26}$ TemplateName: type: string description: >- A template prefix, a namespace path ending in `/*`, such as `acme/prod/*` (§7.7). Up to 256 bytes. pattern: ^[A-Za-z0-9._:/-]+/\*$ minLength: 3 maxLength: 256 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' SubscriptionStatus: type: string description: >- `syncing` until the first pass in the namespace has recorded which documents match, without events for them; then `live`. enum: - syncing - live Timestamp: type: string format: date-time description: RFC 3339, UTC. SubscriptionWarning: type: object description: >- Something that stops the subscription from working as defined, such as a judgment its filter reads that was deactivated. It is never paused or deleted for it. required: - code - message properties: code: type: string enum: - judgment_inactive judgment: $ref: '#/components/schemas/Name' message: type: string 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' 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, `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 judgment units per answer over the sample with this recipe and the definition's 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 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' 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: | 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`. 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`; one that reads the referenced document takes neither. if: properties: join: type: object properties: mine: const: id then: anyOf: - required: - last_n - required: - window else: not: anyOf: - required: - last_n - required: - window properties: match: $ref: '#/components/schemas/AttributeFilter' 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. 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. minItems: 1 items: oneOf: - $ref: '#/components/schemas/RelationField' - $ref: '#/components/schemas/BandedField' aggregate: $ref: '#/components/schemas/Aggregate' 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' RelationJoin: description: | How a related document is matched to the judged one: one side is `id`, the other an attribute holding an id. A join with an attribute on both sides, documents sharing a key, is E3b and `invalid_request`. oneOf: - $ref: '#/components/schemas/ReferringJoin' - $ref: '#/components/schemas/ReferencedJoin' RelationField: type: string description: A path in a related document, `id`, `created_at` or `updated_at`. pattern: ^((state|attributes)(\.[^.]+)+|id|created_at|updated_at)$ BandedField: type: object description: | Entities, E3a (§6.5.2). A number rendered as its band rather than its value, in any relation. A number renders as the label whose position is how many cut points are at or below it: with `bands: [0.3, 0.7]`, 0.29 is `labels[0]`, 0.3 is `labels[1]` and 0.7 or more `labels[2]`. A value that is not a number renders unchanged, and a missing one is left out. Only a move to another band changes the context, so a move inside one neither fans out nor costs an evaluation. `bands` must be strictly increasing and `labels` must have exactly one more entry; the server refuses anything else with `invalid_request`. additionalProperties: false required: - path - bands - labels properties: path: type: string description: A `state` or `attributes` path. pattern: ^(state|attributes)(\.[^.]+)+$ bands: type: array description: Cut points, strictly increasing. minItems: 1 maxItems: 9 items: type: number labels: type: array description: One label per band, lowest first, so one more than `bands`. minItems: 2 maxItems: 10 items: type: string minLength: 1 maxLength: 64 Aggregate: type: object description: | Numbers over the relation's documents, after `match`, `window` and `last_n`, rendered as keys of its `related.` entry, such as `count` and `sum(state.amount)`. At most 8 paths in total. `sum`, `min` and `max` skip values that are not numbers; `sum` of nothing is 0, and `min` and `max` of nothing are null. `latest` is the value in the newest document that has one, of any JSON type. additionalProperties: false minProperties: 1 properties: count: const: true description: How many documents the relation selected. sum: $ref: '#/components/schemas/AggregatePaths' min: $ref: '#/components/schemas/AggregatePaths' max: $ref: '#/components/schemas/AggregatePaths' latest: $ref: '#/components/schemas/AggregatePaths' AttributeFilterValue: type: - string - number - boolean ReferringJoin: type: object description: | Entities, E1 (§6.5.2). The documents that point at the judged one: a related document belongs to the judged document whose `id` equals its `theirs` attribute. additionalProperties: false required: - theirs - mine properties: theirs: type: string description: >- The related document's attribute that holds the judged document's id, such as `attributes.parent_id`. pattern: ^attributes\.[A-Za-z0-9_-]+$ mine: const: id ReferencedJoin: type: object description: | Entities, E3a (§6.5.2). The one document the judged document points at, its referenced document: the document whose `id` equals the judged document's `mine` attribute. A change to what the relation renders of it re-judges the judged documents that point at it and are inside `freshness.fanout.scope`. additionalProperties: false required: - theirs - mine properties: theirs: const: id mine: type: string description: >- The judged document's attribute that holds the referenced document's id, such as `attributes.group_id`. pattern: ^attributes\.[A-Za-z0-9_-]+$ 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)(\.[^.()]+)+$ 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' PlanRequired: description: >- `plan_required`: the organization's plan does not include this (§9). `details.capability` names what it needs (such as `templates`), `details.required_plan` the cheapest plan that includes it, and `details.plan` the plan the organization is on. An owner changes the plan in the dashboard; retrying does not help. 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' 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' Unavailable: description: >- `unavailable`: something this route needs on our side is not set up or not reachable, such as the key webhook secrets are sealed under. Nothing was changed. Retry later; it is not fixed by changing the request. 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`. ````