Resolve

POST /v1/resolve

Call https://api.blatent.ai/v1/resolve to generate an output using an inline schema or a registered reference. Supply exactly one of schema and schema_id. Authenticate using the API key header.

Request body

input JSON value optional

Material to interpret: text or any JSON value. May be omitted.

schema object | boolean | null one of these two required

An inline JSON Schema. Use this or schema_id, never both.

schema_id string | null one of these two required

An immutable version, digest reference, or alias in your tenant.

model string | null optional

Optional. The only accepted non-null value is blatent-struct-v0.0.1a.

parameters object | null optional

Optional named JSON context values, separate from input and state. Not schema substitution.

user_context object | null optional

Optional user scopes and attributes supplied by your backend. Forward verified claims, never OAuth tokens.

state object | null optional

Optional application context. Inline state is not persisted.

policy object | null optional

Inline OPA definition. Use policy or policy_id, not both. Requires a policy-capable deployment.

policy_id string | null optional

Tenant-owned immutable policy version or digest reference.

policy_max_retries integer | null optional

Maximum retries after the first attempt: 0–128; defaults to 32 when a policy is bound.

policy_feedback string | null optional

Optional recovery guidance: off, chat or inline. Requires a policy binding; changes subsequent conditioning.

model, input, parameters, user_context, state and policy bindings are optional. parameters supplies named JSON context values; it does not substitute placeholders in the schema. You do not need optional context for a basic request. user_context accepts scopes (an array of permission names) and attributes (a JSON object). Supply verified claims from your application; never send OAuth tokens.

Use policy or policy_id, never both. Retry/feedback settings require a non-null policy binding. See OPA policies.

Unknown request fields are rejected. Setting both schema selectors, or providing neither, returns 422.

Success

200 OK. Read the generated value from output. Illustrative response excerpt:

{"output":{"department":"billing","duplicate":true}}

Your schema describes output, not the surrounding response. Other fields identify the request and its result:

Field	Meaning
output	The generated JSON value. Its type comes from your schema.
model	blatent-struct-v0.0.1a
schema_id	The supplied registered reference; null for an inline schema.
schema_digest	Identity of the schema content.
state	The supplied state snapshot; null when omitted. This is not a state update.
state_version	Null for the inline-state interface.
policy	Present on successful policy-bound requests; described below.
probabilities	Present when a supported field sets "probabilities":true; label permutations are optional. Keyed by output JSON Pointer, with value, probability and log_probability entries.
usage	Contains input_tokens, a nonnegative integer counting billable input tokens.

See candidate probabilities for a complete example. Without label permutations, probability collection preserves ordinary token-by-token selection. With permutations, it exposes their mapped mean distribution. These probabilities are not calibrated confidence that an answer is correct.

usage.input_tokens uses the o200k_base tokenizer over input, state, schema and policy. It is a billing count, not the model's internal token count. The response does not expose the decision count or request price; see pricing for the calculation.

Metadata is extensible. Parse the fields your application needs and allow additional metadata fields.

For successful policy requests, policy contains policy_id (null for inline), digest and status: "allow". No denied candidate is returned as output.

The Server-Timing response header reports server durations in milliseconds. Measure the complete HTTP round trip with a client timer; see latency for the difference.

Failure

Invalid authentication returns 401; a policy denial or account limit returns 403; an unknown reference returns 404; an uncertain outcome returns 409 OUTCOME_INDETERMINATE; a request body over 8 MiB returns 413; request or schema errors return 422; exceeding an account rate limit returns 429; unavailable execution returns 503; full capacity returns 529 and a missed deadline returns 504. See errors.

Example

triage.schema.json

Download triage.schema.json

{
  "type": "object",
  "properties": {
    "department": {
      "type": "string",
      "enum": ["billing", "technical", "other"],
      "description": "Route charges, invoices and refunds to billing. Route broken product behavior to technical. Use other for anything else."
    },
    "duplicate": {
      "type": "boolean",
      "description": "True only when the message explicitly reports being charged more than once for the same purchase."
    }
  },
  "required": ["department", "duplicate"],
  "additionalProperties": false
}

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python

Python

import json
import os
from pathlib import Path
import httpx

request = {
    "input": "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
    "schema": json.loads(Path("triage.schema.json").read_text(encoding="utf-8")),
}
with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    response = client.post("/v1/resolve", json=request)
    response.raise_for_status()
    print(json.dumps(response.json()["output"]))

TypeScript

import { readFileSync } from "node:fs";

const request = {
    "input": "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
    "schema": JSON.parse(readFileSync("triage.schema.json", "utf8")),
};
const response = await fetch(
  "https://api.blatent.ai" + "/v1/resolve",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BLATENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request),
    signal: AbortSignal.timeout(195_000),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(JSON.stringify((await response.json()).output));

cURL

set -eu

body=$(jq -n --argjson body '{"input":"The invoice was charged twice. Can you help me get the duplicate charge refunded?"}' \
  --slurpfile f0 'triage.schema.json' \
  '$body | setpath(["schema"]; $f0[0])')
curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/resolve" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary "$body"

Contract download

Download the OpenAPI definitions for request and response schemas, authentication, health checks and HTTP statuses.

For a complete request, use the first-request example.