Authentication
All endpoints on api.obligationsign.com require a Bearer token:
Authorization: Bearer agts_live_...
Obtain your API key via POST /auto-register (free trial) or from the dashboard. Keys are prefixed agts_live_ (production) or agts_test_ (test mode).
The public log endpoints (log.obligationsign.com/agts/v1/log/*) are unauthenticated — they are public by protocol specification.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| ENROLLMENT | |||
POST | /auto-register | None | Provision trial tenant. Returns api_key, tenant_id, node_id, log_url, dashboard URL. |
GET | /account | Bearer | Tenant info, tier, trial status, leaf count, subscription_id. |
POST | /api-key/rotate | Bearer | Rotate API key. Old key expires after 24h. |
| GOVERNANCE | |||
POST | /governance/evidence | Bearer | Submit gate evidence. Assembles proof bundle → validator round → envelope → log admission. Returns leaf_hash, compliance_url. |
GET | /governance/report/:artifact_hash | Bearer | Retrieve AGTS_COMPLIANCE_REPORT_V1 for a proof bundle. Export (JSON/Markdown) requires L2. |
GET | /governance/chain | Bearer | Paginated list of proof bundles for tenant. Query params: page, limit, from, to. |
GET | /governance/status | Bearer | Current clearinghouse state: lifecycle, HCE observables, consecutive_fails, trial_leaves_remaining. |
| CLOSED LOOP (L2+) | |||
POST | /governance/execution | Bearer | Submit execution trace against an authorization leaf. Triggers variance computation. Returns exec_leaf_hash, variance_leaf_hash. |
GET | /governance/variance/:auth_leaf_hash | Bearer | Retrieve AGTS_VARIANCE_RECORD_V1 for an authorization leaf. |
GET | /governance/triple-leaf/:auth_leaf_hash | Bearer | Retrieve all three leaves (auth + exec + variance) for a governed action. |
| TRANSPARENCY LOG (public) | |||
GET | /agts/v1/log/sth | None | Current Signed Tree Head. Fields: log_id, tree_size, root_hash, timestamp, log_signature, witness_signatures. |
GET | /agts/v1/log/leaf?index=N | None | Leaf hash + envelope reference at index N. |
GET | /agts/v1/log/proof?leaf_hash=H | None | Merkle inclusion proof for leaf hash H. |
GET | /agts/v1/log/consistency?from=M&to=N | None | Consistency proof between tree sizes M and N. |
| WEBHOOKS | |||
POST | /webhooks | Bearer | Register webhook endpoint. Body: {url, events[], secret?}. |
GET | /webhooks | Bearer | List registered webhooks. |
DELETE | /webhooks/:id | Bearer | Remove webhook. |
POST /governance/evidence
The core endpoint. Submit governance evidence for a decision. Returns a canonical leaf hash.
Request body
{
"subject_id": "customer-chatbot:response-policy:v1.2",
"gate_results": {
"G1": {
"result": "PASS",
"confidence_interval_lower": 0.80,
"confidence_interval_upper": 0.95,
"bootstrap_iterations": 10000
},
"G2": {
"result": "PASS",
"causal_attribution": true,
"ablation_delta": 0.031
},
"G3": {
"result": "PASS",
"protected_metrics": { "toxicity_score": 0.02, "safety_score": 0.96 }
},
"G4": {
"result": "PASS",
"evidence_class": "HOOKED"
},
"G5": {
"result": "PASS",
"operator_id": "alice@example.com"
}
},
"evidence": {
"dataset_provenance_hash": "<sha256-hex>",
"evaluation_trace_hash": "<sha256-hex>",
"ablation_execution_log_hash": "<sha256-hex>",
"capability_certificate_hash": "<sha256-hex>"
},
"replay_seed": "<hex-or-uri>",
"state_before_hash": "<sha256-hex>",
"state_after_hash": "<sha256-hex>"
}
Response (201 Created)
{
"leaf_index": 42,
"leaf_hash": "8f3a1b...",
"artifact_hash": "c7d9e2...",
"compliance_url": "https://api.obligationsign.com/governance/report/c7d9e2...",
"replay_url": "https://obligationsign.com/replay?leaf=8f3a1b...",
"sth": {
"tree_size": 43,
"root_hash": "...",
"timestamp": "2026-03-14T14:30:00Z",
"log_signature": "..."
}
}
Gate failure response (422 Unprocessable Entity)
{
"error": "GATE_FAILURE",
"gates_failed": ["G1", "G3"],
"details": {
"G1": "confidence_interval_lower (0.62) is below the declared threshold (0.70)",
"G3": "protected metric toxicity_score (0.15) exceeds declared maximum (0.05)"
},
"action": "ACTION_BLOCKED"
}
Error codes
| HTTP status | Error code | Meaning | Resolution |
|---|---|---|---|
| 400 | INVALID_REQUEST | Missing required field or invalid format | Check request body against schema above |
| 401 | UNAUTHORIZED | Missing or invalid Bearer token | Check api_key; rotate if needed |
| 403 | TIER_INSUFFICIENT | Action requires higher tier | See pricing for tier capabilities |
| 409 | TRIAL_EXHAUSTED | Free tier: 5-leaf limit or 72h window reached | Upgrade to Pay-as-you-govern |
| 422 | GATE_FAILURE | One or more gates rejected the evidence | Check gates_failed and details fields |
| 422 | PARENT_AUTH_NOT_FOUND | Execution trace references non-existent auth leaf | Verify parent_auth_leaf_hash corresponds to an admitted leaf |
| 422 | EVIDENCE_CLASS_INVALID | G4 evidence_class not in {HOOKED, ATTESTED, INSTRUMENTED} | Use only the three valid evidence classes |
| 429 | RATE_LIMITED | Too many requests | Free: 100 leaves/day. Paid tiers: higher limits. Retry-After header is set. |
| 500 | INTERNAL_ERROR | Log worker or validator network error | Check /log for STH status. Retry with exponential backoff. |
Rate limits
| Tier | Leaves/day | API requests/min |
|---|---|---|
| Trial (L1) | 100 (hard cap: 5 total) | 60 |
| Pay-as-you-govern (L2) | Depends on credit balance | 300 |
| Certified (L2+) | Unlimited (shared log) | 1,000 |
| Networked (L4) | Unlimited (dedicated log) | Custom |