What does a POST to OPA's /v1/data endpoint send and return?

## Asking OPA a question over HTTP OPA answers one thing at a time: *what is the value of this document, given these facts?* Over HTTP that question is a request to the Data API, and every integration detail follows from its two envelopes - one around what you send, one around what comes back. ### The URL is a document path, not a file name Rego rules live in packages. A rule named `allow` inside `package db.policy` is the document `data.db.policy.allow`. On the wire the `data` root becomes the `/v1/data` prefix and the dots become slashes, so the URL is `/v1/data/db/policy/allow`. Several `.rego` files can contribute rules to the same package; the file names never appear in the URL and are irrelevant to the caller. You also choose how deep to point. `/v1/data/db/policy/allow` asks for one value. `/v1/data/db/policy` asks for the whole package document - an object with a key for every rule in it that is defined. Pointing at a single named decision is almost always the better client contract: the response stays one value with one meaning, instead of a snapshot of whatever the policy currently happens to contain, including helper rules a policy author is free to rename tomorrow. ### The facts go under `input` The POST body is `{"input": { ... }}`. Whatever you put inside that field is the `input` document the policy sees. Two nearby things it is not: - **`data`** is OPA's own stored state - documents loaded from a bundle or pushed with `PUT /v1/data/...`. That is the standing information the engine already has, like a list of approved database engines. It is not part of your request. - **The URL path** selects *what to evaluate*, not *what to evaluate it against*. Putting a resource id in the path does not make it visible to the rule. A `GET` on the same path evaluates the document with no input supplied, which only makes sense for documents that depend purely on stored data. A concrete example. Suppose the rule enforces that a managed database may not be created with a backup retention window under thirty days. The provisioning service, before it calls the cloud API, posts the spec it is about to submit: ``` POST /v1/data/db/policy/allow {"input": {"action": "create", "resource": {"type": "managed_database", "backup_retention_days": 7}}} ``` and gets `{"result": false}` back. It then refuses to make the call. ### The answer comes back under `result` A successful evaluation is `200` with `{"result": <value>}`. The value is whatever the document evaluated to - a boolean, an object, an array of messages. Two consequences get probed constantly: 1. **Status is about evaluation, verdict is in the body.** `200` means OPA ran the query without an error. `400` means it could not read your request, `500` means evaluation itself failed, and a connection error means the engine is not there. None of those are denials, and a denial is not any of those - it is a `200` whose body says `false`. Enforcement points that check `response.ok` and proceed are not enforcing anything. 2. **An undefined document has no `result` field at all.** You get `200` and the body `{}`. This is the single most expensive detail in the whole API, because the shape of a 'no decision' is indistinguishable at the transport layer from a healthy call. Requests can also ask for extras alongside the result - timing metrics, or an evaluation trace - which arrive as sibling fields in the same object. They are diagnostics; the decision is always the `result` field. ### v0 versus v1 shapes OPA also exposes `/v0/data/<path>`, kept for simple webhook-style callers that cannot reshape their payload. There, the **request body is the input document itself** (no `input` wrapper) and the **response body is the value itself** (no `result` wrapper). Same evaluation, different envelope. Mixing them up is a classic integration bug and it fails quietly in both directions. Point a v0-shaped caller at a v1 URL and there is no `input` field in the body, so the rule sees nothing and evaluates against an empty input. Point a v1-shaped caller at a v0 URL and the whole `{"input": ...}` object becomes the input document, so every reference in the policy is off by one level - the rule looks for `input.resource` and the actual value is at `input.input.resource`. Neither produces an error status; both produce wrong decisions. ### What to carry away The wire contract is small: path names the document, `input` carries the facts, `result` carries the answer, and the status code tells you only whether OPA could answer at all. Build the client around the body, decide up front what it does when the body has no `result` in it, and pin the exact path you query in a test so that a package rename does not silently turn your gate off.