REST API
Alignment
On this page
Alignment checks agent behaviour against your written policy. You upload the policy documents; the alignment engine flags where agent output diverged from them.
Get alignment policy
GET /v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy
Auth: API key or JWT · Role: viewer
Response 200 — not schema-modelled
{ "enabled": true, "description": "Support agents must never promise a refund window shorter than 30 days." }
Examples
p = evigauge.get("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy")
print(p["enabled"], p["description"])
const p = await evigauge.get("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy");
console.log(p.enabled, p.description);
Set alignment policy
PUT /v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy
Auth: API key or JWT · Role: admin
Request body — _PolicyBody
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
description | string | ➖ | "" | Natural-language statement of the policy |
enabled | boolean | ➖ | false | Whether the alignment engine runs for this workspace |
Examples
evigauge.put("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy", json={
"enabled": True,
"description": "Never promise a refund window shorter than 30 days.",
})
await evigauge.put("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/policy", {
enabled: true,
description: "Never promise a refund window shorter than 30 days.",
});
Upload an alignment document
POST /v1/observ/orgs/{org}/workspaces/{ws}/alignment/docs
Upload a policy document. Ingestion is asynchronous — the document is chunked and embedded into the workspace's vector store before it influences flags.
Auth: API key or JWT · Role: admin
Request body — multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | ✅ | The document to upload |
Examples
import httpx, os
with open("refund-policy.pdf", "rb") as fh:
r = httpx.post(
"https://api.opexia.dev/v1/observ/orgs/acme/workspaces/prod/alignment/docs",
headers={"x-opexia-api-key": os.environ["OPEXIA_API_KEY"]},
files={"file": ("refund-policy.pdf", fh, "application/pdf")},
timeout=120,
)
r.raise_for_status()
print(r.json())
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append(
"file",
new Blob([await readFile("refund-policy.pdf")], { type: "application/pdf" }),
"refund-policy.pdf",
);
const res = await fetch(
"https://api.opexia.dev/v1/observ/orgs/acme/workspaces/prod/alignment/docs",
{ method: "POST", headers: { "x-opexia-api-key": process.env.OPEXIA_API_KEY! }, body: form },
);
console.log(await res.json());
Do not set
content-typemanually on a multipart request. Bothhttpxandfetchderive the boundary automatically; overriding it corrupts the body.
Delete an alignment document
DELETE /v1/observ/orgs/{org}/workspaces/{ws}/alignment/docs/{doc_id}
Removes the document and its embeddings from the workspace store.
Auth: API key or JWT · Role: admin
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | ✅ | Organization slug |
ws | string | ✅ | Workspace slug |
doc_id | string | ✅ | Document ID returned at upload |
Examples
evigauge.delete(f"/v1/observ/orgs/{{org}}/workspaces/{{ws}}/alignment/docs/{doc_id}")
await evigauge.del(`/v1/observ/orgs/{org}/workspaces/{ws}/alignment/docs/${docId}`);
List alignment flags
GET /v1/observ/orgs/{org}/workspaces/{ws}/alignment/flags
Cases where agent output diverged from policy.
Auth: API key or JWT · Role: viewer
Query parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | ➖ | 50 | Page size |
offset | integer | ➖ | 0 | Offset for paging |
include_unclear | boolean | ➖ | false | Include low-confidence flags the engine could not resolve |
This endpoint uses offset paging, not cursors — it is one of the few that does.
Response 200 — not schema-modelled
{
"flags": [
{
"flag_id": "af_01J8...",
"trace_id": "4bf92f...",
"policy_excerpt": "Refunds are available for 30 days from delivery.",
"agent_output": "You can request a refund within 14 days.",
"severity": "high",
"confidence": 0.91,
"created_at": "2026-09-01T14:23:05Z"
}
],
"total": 1
}
Examples
f = evigauge.get("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/flags",
params={"limit": 25, "include_unclear": False})
for x in f["flags"]:
print(f"[{x['severity']}] {x['trace_id']}: {x['agent_output'][:70]}")
const f = await evigauge.get(
"/v1/observ/orgs/{org}/workspaces/{ws}/alignment/flags",
{ limit: 25, include_unclear: false },
);
f.flags.forEach((x: any) =>
console.log(`[${x.severity}] ${x.trace_id}: ${x.agent_output.slice(0, 70)}`));
Alignment by user
GET /v1/observ/orgs/{org}/workspaces/{ws}/alignment/by-user
Alignment flags aggregated per end user (opexia.end_user), showing which users'
sessions most often produce policy divergence.
Auth: API key or JWT · Role: viewer
Examples
bu = evigauge.get("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/by-user")
print(bu)
const bu = await evigauge.get("/v1/observ/orgs/{org}/workspaces/{ws}/alignment/by-user");
console.log(bu);
Requires that your instrumentation sets the
opexia.end_userspan attribute. Without it this endpoint returns an empty result rather than an error.