REST API (v2)

POST /schemas/:version/resolve

Compose a thin DatachainInstance plus the pinned schema slice into a ResolvedDatachainInstance.

POST /schemas/:version/resolve

Resolve runs validate first (R7). On semantic failure, the response is HTTP 200 with { "ok": false, "errors": [...] } mirroring the /validate envelope.

Summary

Compose a thin DatachainInstance and the pinned schema's lean subset (datachain_type + referenced categories + referenced elements) into a single self-contained ResolvedDatachainInstance. Downstream consumers can render the snapshot offline, ship it to product surfaces / PDFs / admin UIs, or persist it as an audit artifact — no further schema fetch required.

ResolvedDatachainInstance is a strict structural superset of DatachainInstance. Stripping schema_snapshot, suggested_elements, and authoring_provenance returns a thin instance equivalent (post-parse) to the input.

Request

POST https://api.dtpr.io/api/v2/schemas/:version/resolve
Content-Type: application/json

{
  "id": "acme-resume-screener",
  "title": [{ "locale": "en", "value": "Acme resume screener" }],
  "description": [{ "locale": "en", "value": "Pre-screens job applicants against the role brief." }],
  "schema_version": "dtpr@2026-09-01-beta",
  "created_at": "2026-09-01T00:00:00Z",
  "elements": [
    { "element_id": "employment" },
    {
      "element_id": "organization",
      "context_type_id": "deployer",
      "variables": [
        { "id": "title", "value": [{ "locale": "en", "value": "Acme Corp" }] },
        { "id": "description", "value": [{ "locale": "en", "value": "Runs the screener and makes the final hiring call." }] }
      ]
    },
    {
      "element_id": "people",
      "context_type_id": "subject",
      "variables": [
        { "id": "title", "value": [{ "locale": "en", "value": "Job applicants" }] },
        { "id": "description", "value": [{ "locale": "en", "value": "Anyone who submits a resume for an open role." }] }
      ]
    },
    { "element_id": "recommends", "context_type_id": "human_decides" }
  ]
}

Param	In	Description
`version`	path	Canonical version.
(body)	JSON	A `DatachainInstance`. `id`, `schema_version`, `created_at`, and a non-empty `elements[]` are required.

Response — success

HTTP/1.1 200 OK
Content-Type: application/json
DTPR-Content-Hash: sha256-…
Cache-Control: no-store

{
  "id": "acme-resume-screener",
  "schema_version": "dtpr@2026-09-01-beta",
  "created_at": "2026-09-01T00:00:00Z",
  "elements": [ "/* the placements from the request, unchanged */" ],
  "schema_snapshot": {
    "datachain_type": { "id": "dtpr", "categories": ["purpose", "accountable", …], "subchains": […], … },
    "categories": [{ "id": "accountable", … }, { "id": "action", … }, { "id": "affected", … }, { "id": "purpose", … }],
    "elements": [{ "id": "employment", … }, { "id": "organization", … }, { "id": "people", … }, { "id": "recommends", … }]
  },
  "suggested_elements": []
}

Response — semantic failure (R7)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": false,
  "errors": [
    { "code": "INSTANCE_ELEMENT_UNKNOWN", "message": "…", "path": "elements[0]" }
  ]
}

Response — payload too large

When the resolved bundle exceeds the 512 KB cap, the response is 413 Payload Too Large:

HTTP/1.1 413 Payload Too Large
Content-Type: application/json

{
  "ok": false,
  "errors": [
    {
      "code": "payload_too_large",
      "message": "Resolved bundle exceeds 524288-byte cap (got 612904).",
      "fix_hint": "Reduce locales/elements/categories pinned by the schema, or fetch the schema content separately."
    }
  ]
}

Limits

Limit	Value	Source
Rate limit	15 req / 60 s	`RL_RESOLVE` binding (shared with `validate_resolved`).
Wall-clock	5000 ms	Per-route timeout middleware.
CPU	500 ms	Worker-wide ceiling (`limits.cpu_ms` in `wrangler.jsonc`).
Response cap	512 KB	Measured against the canonical (sorted-key) serialization.

Errors

Code	HTTP	Meaning
`bad_request`	400	Invalid JSON body or malformed `:version`.
`not_found`	404	Version is not registered.
`parse_error`	200	Datachain shape failed Zod validation.
`payload_too_large`	413	Resolved bundle exceeds 512 KB cap.
Semantic validator codes	200	Shape-valid but semantically wrong (R7 — validate runs before resolve).