Physical Authority API Reference#

This is the contract for direct HTTP integration against /v1/physical/* — every field below is matched to the runtime (services/api/src/routes/physical.ts). Use it when there is no SDK for your language, or when you need the exact wire format for a verifier.

Base URL and authentication#

https://api.intended.so

Every endpoint requires a verified tenant context. Present a tenant-scoped API key and the tenant header on every call:

Authorization: Bearer mrt_live_…
x-tenant-id:   tenant_acme_prod
Content-Type:  application/json

A request that cannot resolve a verified tenant is rejected with 401 unauthenticated. The API key authenticates the caller; it does not bind a token to a robot. What binds an issued token to a specific robot is the actorIdentity claim — and that actor must be registered on the tenant roster first (see POST /v1/physical/actors).

Endpoint summary#

Error envelope#

All non-2xx responses use a nested envelope:

{
  "error": {
    "code": "validation_error",
    "message": "human-readable explanation",
    "details": { "issues": [ "…" ] }
  }
}

details is present only on some errors. Validation failures carry details.issues (the Zod issue list). Policy denials carry details with the deciding clause and safe-default (see below).

POST /v1/physical/classify

Classifies a structured goal into an OI category. Does not issue a token. Useful when your pipeline wants to inspect the classification before deciding whether to request authority.

StructuredGoal fields

Request

{
  "goal": {
    "schema": "ros2:action:moveit_msgs/Pick",
    "verb": "pick",
    "object": "workpiece-A4-7",
    "parameters": { "frame_id": "cell_origin" },
    "actor": { "kind": "cobot", "identifier": "cobot-east-3" }
  }
}

Response 200

{
  "oiCode": "OI-1502",
  "confidence": 0.97,
  "safetyBit": true,
  "safetyCitations": ["OI-2903", "OI-2904", "OI-2906"],
  "alternatives": [{ "oiCode": "OI-1801", "confidence": 0.86 }],
  "failClosed": false,
  "explanation": "MoveIt / manipulation primitive."
}

POST /v1/physical/authority-tokens

Runs the full authority loop and, on ALLOW, mints the token. The endpoint will classify the goal itself if you omit intent.oiCode.

Headers

Request fields

Response 200 — ALLOW

{
  "decision": "ALLOW",
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imt…",
  "oiCode": "OI-1502",
  "expiresAtMs": 1735689600200,
  "safetyBit": true,
  "safetyCitations": ["OI-2903", "OI-2904", "OI-2906"],
  "physicalStateRef": "state_…",
  "tokenJti": "01HQ…"
}

physicalStateRef is null when no physicalState was submitted. The token is the RS256 JWT detailed in Token claims.

Response 200 — ESCALATE

{
  "decision": "ESCALATE",
  "escalationTicketId": "esc_…",
  "approvalUrl": "https://app.intended.so/approvals/esc_…",
  "safeDefault": "request-operator",
  "expiresAtMs": 1735689660000
}

expiresAtMs here is the ticket TTL (one hour), not a token TTL. Poll /approvals/{ticketId}; once approved, re-call this endpoint with operatorTicketId set.

Response 422 (or 423) — DENY

{
  "error": {
    "code": "policy_denied",
    "message": "deny-on-emergency-stop: safety/emergency_stop == true",
    "details": {
      "decision": "DENY",
      "clauseId": "deny-on-emergency-stop",
      "safeDefault": "stop",
      "safetyBit": true,
      "safetyCitations": ["OI-2901", "OI-2902"]
    }
  }
}

When the classifier fails closed (no oiCode supplied and no rule matched), the same 422 policy_denied envelope is returned with details.clauseId: "classifier-fail-closed" and details.explanation. When the deciding clause is an audit-gap clause, the status is 423.

Failure modes for this endpoint

The full ALLOW / ESCALATE / DENY branch is illustrated below.

One request, three terminal outcomes. ALLOW mints a token bound to the action; ESCALATE waits on a human; DENY (422, or 423 for audit-gap) carries the clause's safe-default.

POST /v1/physical/authority-tokens/{jti}/revoke

Revokes a previously-issued token. The jti must correspond to an audit entry for this tenant (else 404 not_found).

Request

{ "reason": "operator-recall: cell evacuated" }

Response 200

{ "tokenJti": "01HQ…", "revokedAtMs": 1735689700000 }

GET /v1/physical/revocations

The endpoint a verifier polls to keep its local revocation list current.

Query

Response 200

{
  "revocations": [
    { "tokenJti": "01HQ…", "revokedAtMs": 1735689700000, "reason": "operator-recall: cell evacuated" }
  ],
  "asOfMs": 1735689701234
}

Poll with since set to the previous response's asOfMs to fetch only new revocations. The server returns at most 1000 entries per call, oldest first.

POST /v1/physical/snapshots

Records a PhysicalStateProvider snapshot in the audit chain without issuing a token — useful for forensic checkpoints or pre-staging state.

Request

{
  "physicalState": {
    "safety/emergency_stop": {
      "kind": "boolean", "value": false, "asOfTimestampMs": 1735689600000,
      "attestation": { "channel": "cell-safety-plc/estop-chain", "safetyRated": true, "protocol": "profisafe" }
    }
  }
}

Response 200

{ "physicalStateRef": "state_…", "asOfTimestampMs": 1735689600000 }

GET /v1/physical/audit/{jti}

Returns the audit-chain entry for a previously-issued token (scoped to your tenant).

Response 200

{
  "tokenJti": "01HQ…",
  "tenantId": "tenant_acme_prod",
  "issuedAtMs": 1735689600000,
  "expiresAtMs": 1735689600200,
  "actorIdentity": "cobot-east-3",
  "oiCode": "OI-1502",
  "decision": "ALLOW",
  "structuredGoal": { "…": "…" },
  "dagNode": { "…": "…" },
  "physicalStateRef": "state_…",
  "physicalState": { "…": "…" },
  "safetyBit": true,
  "safetyCitations": ["OI-2903", "OI-2904", "OI-2906"],
  "verifications": []
}

verifications is an array of { atMs, edgeNodeId, result } entries appended as edge verifiers report checks. It is empty today — edge-verifier reporting is roadmap.

GET /v1/physical/audit

Lists audit entries for the tenant, most recent first.

Query

Response 200: { "entries": [ … ] } — each entry has the shape above.

GET /v1/physical/approvals

Operator inbox — lists escalation tickets, most recent first.

Query

Response 200: { "tickets": [ … ] }.

GET /v1/physical/approvals/{ticketId}

Polls one ticket.

{
  "ticketId": "esc_…",
  "tenantId": "tenant_acme_prod",
  "status": "pending",
  "approvedBy": null,
  "approvedAtMs": null,
  "rejectionReason": null,
  "expiresAtMs": 1735689660000,
  "intent": { "oiCode": "OI-1502", "structuredGoal": { "…": "…" } },
  "createdAtMs": 1735689600000
}

A pending ticket past expiresAtMs is reported as expired. When status == "approved", re-issue against /authority-tokens with operatorTicketId set.

POST /v1/physical/approvals/{ticketId}/decide

Operator approves or rejects a pending ticket.

Request

Response 200: the updated ticket. Deciding a ticket that is no longer pending returns 409 conflict; an unknown ticket returns 404 not_found.

POST /v1/physical/actors

Registers (or updates) an actor on the tenant fleet roster. Idempotent on (tenantId, actorIdentity).

Request

Response 200

{
  "id": "…",
  "tenantId": "tenant_acme_prod",
  "actorIdentity": "cobot-east-3",
  "actorIdentityKind": "ieee-802-1ar-devid",
  "actorKind": "cobot",
  "displayName": "Cell East — UR10e",
  "status": "active",
  "metadata": null
}

GET /v1/physical/actors

Returns { "actors": [ … ] }, most recently registered first.

POST /v1/physical/policy

Uploads a tenant-specific policy. Until a tenant uploads its own, the runtime uses the default policy (deny on emergency-stop, light-curtain breach, human-in-cell).

Request

Response 200: { "id": "…", "version": 3, "active": true }. Uploads are versioned per tenant.

GET /v1/physical/policy

Returns the active policy: { "active": { … } | null, "version": 3 | null, "activatedAt": "…" | null }.

Token claims#

The minted token is an RS256 JWT ({ "alg": "RS256", "typ": "JWT", "kid": … }). Standard and physical claims:

Wire format#

PhysicalStateValue

A discriminated union on kind:

type PhysicalStateValue =
  | { kind: "boolean";     value: boolean; asOfTimestampMs: number; attestation: Attestation }
  | { kind: "number";      value: number;  unit?: string; asOfTimestampMs: number; attestation: Attestation }
  | { kind: "string";      value: string;  asOfTimestampMs: number; attestation: Attestation }
  | { kind: "unavailable"; reason: string; asOfTimestampMs?: number };

type Attestation = {
  channel:     string;
  safetyRated: boolean;   // default false
  protocol:    "fsoe" | "profisafe" | "pilz-pss" | "opc-ua-safety"
             | "ros2-quality-of-service" | "trusted-bus" | "untrusted";  // default "untrusted"
};

The unavailable variant carries no attestation; it represents a predicate your provider could not resolve. Policy clauses that require safety-rated input treat unavailable (and untrusted) channels as failing.

safeDefault enum#

"stop" | "hold-position" | "request-operator" |
"transition-safe-state" | "abort-mission" | "ignore"

ignore is for non-safety-critical actions; it should not appear in any clause covering an OI-29xx (Embodied AI Safety) category.

realTimeTier enum#

"best-effort" | "rt-soft" | "rt-hard"

Idempotency#

POST /v1/physical/authority-tokens honors an Idempotency-Key header. The same key with the same body within 24 hours replays the original status and body (including stored DENY/ESCALATE responses). The same key with a different body returns 409 conflict. A key first used by another tenant returns 403 forbidden. Recommended: dagNodeId + a monotonic counter.

See also#

• Quickstart — the same flow end-to-end.
• packages/contracts/src/physical-ai.ts↗ — the Zod schemas these tables are generated from.
• Safety-case writing — how to argue this surface in a deployment safety case.