Quickstart | Concepts | API | Verify
API
Base URL: https://witness.sipkigroup.com. JSON bodies, bytes are base64url without padding (*_b64), times are Unix seconds. Errors: {"error": "<CODE>", "detail": "..."}. The machine-readable form is cloud/contract/openapi.yaml.
Agent API (Bearer key dwk_...)
| call | body | answer |
|---|---|---|
POST /v1/actions | {tool, args, client?} | ActionResult |
GET /v1/actions/{rid}?wait=0..25 | ActionResult (long poll while pending_approval) | |
POST /v1/actions/{rid}/present | {} | {result: accept|reject, reason} (consumes the receipt, call before executing) |
POST /v1/actions/{rid}/report | {executed: bool} | {result: released|ignored} |
GET /v1/witness | {iss, alg, kid_hex, pub_hex, web_js_sha256} |
ActionResult: {rid, verdict: allow|deny|defer|pass, reason, status, action, expires, aar_b64, proof, approval_url}. Repeating the same request while it is pending or approved returns the same action. Limits: 60 requests/min per key (429 RATE_LIMIT), 5000 actions/day per account (429 QUOTA). Since 0.1.1 proof is null in the POST answer for an allow (the receipt aar_b64 is there at once); GET /v1/actions/{rid} returns the inclusion proof (proofs of a batch share one checkpoint). A repeat of an action the owner refused returns deny REFUSED without a new approval request.
Request body limit: 256 KB (413 BODY_TOO_LARGE). Witness.act(..., verify=True) and the proxy check that the receipt is for the call that was sent (REQUEST_MISMATCH).
TypeScript SDK (sdk-ts): no verification of receipts yet - it returns what the server says; use the Python SDK or the proxy where the receipt matters.
Python SDK (in the wheel):
from deus_witness import Witness
w = Witness("https://witness.sipkigroup.com", "dwk_...")
r = w.act("send_email", {"to": "bob@acme.example", "subject": "hi", "body": "..."})
if r.verdict == "allow" and w.present(r.rid)["result"] == "accept":
... # do the thing
w.report(r.rid, True)Web API (cookie dw_session; writes need Origin equal to the site origin)
Auth: POST /api/auth/register/begin|finish, login/begin|finish, logout; GET /api/me.
Agents: GET|POST /api/agents, PUT /api/agents/{id}/toolmap, DELETE /api/agents/{id}; GET|PUT /api/data-patterns.
Mandates: POST /api/mandates/draft (form -> mandate map), POST /api/mandates ({mandate, envelope_b64}), GET /api/mandates.
Activity: GET /api/feed?agent_id=&before=&limit= , GET /api/budget, GET /api/approvals?status=pending, GET|POST /api/approvals/{rid}.
Export: GET /api/export (evidence pack zip; 6 per hour per account, 429 RATE_LIMIT). GET /healthz -> {ok, ledgers, last_anchor_t}.
The signing envelope (wa-sig) is specified in cloud/contract/PROFILE-webauthn-00.md; test vectors are in cloud/contract/vectors.