Read the Policy

Read the effective tenant AI policy: mandatory routing constraints, the per-operation class map, resolved defaults, and live satisfiability status in one call.

GET /v1/ai/policy returns the caller's own policy as it is enforced right now: the stored policy document, the mandatory constraints derived from it, the per-operation class map, and a live satisfiability status. It is the single read that answers a compliance review's first three questions at once: what did we configure, what is actually being enforced, and does the configuration currently leave every operation with a route.

The distinction between policy and constraints matters. policy is the stored document, exactly what was written, including preference fields like default_models and model_substitutions. constraints is the enforced view: the workspace's mandatory constraints folded together with the platform provider floor. When the two disagree, constraints is what routing obeys, and constraints.platform_provider_floor shows the deployment-level bound the workspace cannot widen past.

inherited: true means the workspace has stored no policy of its own and runs on the platform default. The operation_classes map shows, for every operation type, the class it resolves to, where that mapping came from (builtin, platform, or org), and whether the workspace overrode it. The status block is evaluated live: satisfiable reports whether every registered operation currently has a compliant route, unroutable_operations names the ones that do not, and advisory_warnings names operations that are unroutable but only warn.

GET/v1/ai/policy

Response fields

policyobjectThe stored policy document: version, status, region_pin, allowed_providers, denied_models, model_substitutions, default_models, max_attempts, model_classes, operation_classes, features. Unset fields are null.

inheritedbooleanTrue when the workspace has no stored policy and runs on the platform default.

constraintsobjectThe enforced mandatory constraints: region_pin, allowed_providers, denied_models, and platform_provider_floor (the deployment-level bound the tenant policy can only narrow, never widen).

operation_classesobjectPer operation type: { class, source, overridden }. source is builtin, platform, or org; overridden is true when the workspace remapped the operation.

status.satisfiablebooleanWhether every registered operation currently has a compliant route under this policy.

status.unroutable_operationsstring[]Registered operations with no compliant route. Non-empty only when satisfiable is false.

status.advisory_warningsstring[]Advisory operations with no compliant route. These warn but never block activation.

cURL: Read the policy

curl "https://api.talonic.com/v1/ai/policy" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: Effective policy

{
  "policy": {
    "version": 4,
    "status": "active",
    "region_pin": "eu",
    "allowed_providers": ["bedrock"],
    "denied_models": ["claude-opus"],
    "model_substitutions": null,
    "default_models": null,
    "max_attempts": null,
    "model_classes": null,
    "operation_classes": { "extraction": "complex" },
    "features": null
  },
  "inherited": false,
  "constraints": {
    "region_pin": "eu",
    "allowed_providers": ["bedrock"],
    "denied_models": ["claude-opus"],
    "platform_provider_floor": ["bedrock"]
  },
  "operation_classes": {
    "extraction": { "class": "complex", "source": "org", "overridden": true }
  },
  "status": {
    "satisfiable": true,
    "unroutable_operations": [],
    "advisory_warnings": ["document_ocr"]
  }
}

Every successful write (PUT or PATCH) echoes this exact body after a saved field, so a writer never needs a follow-up read to learn what the policy became. The status block in the write response is the post-write satisfiability, evaluated against what was actually stored.

A non-empty advisory_warnings is informational, not an error state. In the example above, the EU pin on one provider leaves document_ocr without a compliant route; because OCR is advisory rather than registered, the policy still activates, and OCR calls in that workspace fail closed until the policy widens. This is a legitimate configuration for a customer whose contract covers extraction but not a third-party OCR provider.

Frequently asked questions

What does inherited: true mean?+

The workspace has never stored a policy of its own and runs on the platform default. The constraints and operation_classes in the response still describe what is enforced; they are simply derived from the default rather than from a workspace-stored document. The first successful write flips inherited to false.

Why do policy and constraints both list region_pin and denied_models?+

policy is the stored document as written; constraints is the enforced view after intersecting with the platform provider floor. Routing obeys constraints. Reading both side by side shows whether the platform floor narrowed anything beyond what the workspace itself configured.

Why is my key rejected with workspace_scope_required?+

Every /v1/ai route acts on exactly one workspace, taken from the authenticated key. A master-view key spans every workspace, so it has no single policy to read and no workspace to write, and is rejected with 400 workspace_scope_required rather than defaulted to one.

Read the Policy

Frequently asked questions

Related