{"openapi": "3.0.3", "info": {"title": "Resume-effect reconciliation API", "version": "1.0.0", "description": "Before a checkpointed agent run resumes, reconcile which of its external effects already landed: a checkpoint-keyed effect ledger, a read-only probe of the target system when the ledger is silent, and an Ed25519-signed verdict \u2014 SAFE / RESUME-WITH-SKIPS / DO-NOT-RESUME \u2014 plus a journal-completeness audit for killed runs. Payments use x402 v1 (scheme exact, network base, Base USDC to payTo 0xAc2E243a075fEe442e4c6864DcF880eb4e3A3862 = textforagents.base.eth). An unpaid POST /verdict or /subscribe returns 402 with the payment terms in the body (x402.accepts[0]) and an X-Payment-Required: true header; retry with a signed X-PAYMENT header. Demo-target disclosure: Hosted probe disclosure (M2): the hosted service's probe checks a built-in demo target store shared by all effect kinds. Effects that landed in YOUR real systems are visible to it only if you backfill them via POST /effects or run them through POST /effects/execute (which executes against the demo target). For probes of real systems, run the resume_guard package (GET /package) in your own stack.", "contact": {"email": "support@textforagents.com"}}, "servers": [{"url": "https://textforagents.com/products/resume-effect-reconciliation"}], "components": {"securitySchemes": {"BearerAuth": {"type": "http", "scheme": "bearer", "description": "Per-customer token from POST /trial or /subscribe (shown once at issuance)."}}, "schemas": {"Error": {"type": "object", "properties": {"status": {"type": "string", "example": "ERROR"}, "reason": {"type": "string"}}, "required": ["status", "reason"]}, "EffectRequest": {"type": "object", "properties": {"run_id": {"type": "string"}, "checkpoint_ns": {"type": "string"}, "node": {"type": "string"}, "effect_key": {"type": "string"}, "kind": {"type": "string"}, "landed": {"type": "boolean", "default": true}, "result": {"type": "object"}, "payload": {"type": "object"}}, "required": ["run_id", "checkpoint_ns", "node", "effect_key", "kind"]}, "VerdictRequest": {"type": "object", "properties": {"run_id": {"type": "string"}, "checkpoint_ns": {"type": "string"}, "node": {"type": "string"}, "declared_effects": {"type": "array", "items": {"type": "object", "properties": {"effect_key": {"type": "string"}, "kind": {"type": "string"}}, "required": ["effect_key", "kind"]}}, "current_discovery_digest": {"type": "string"}}, "required": ["run_id", "checkpoint_ns", "node", "declared_effects"]}, "VerdictResponse": {"type": "object", "properties": {"verdict": {"type": "object", "properties": {"run_id": {"type": "string"}, "checkpoint_ns": {"type": "string"}, "node": {"type": "string"}, "state": {"type": "string", "enum": ["SAFE", "RESUME-WITH-SKIPS", "DO-NOT-RESUME"]}, "reasons": {"type": "array", "items": {"type": "string"}}, "effects": {"type": "array", "items": {"type": "object"}}, "issued": {"type": "number"}}}, "signature": {"type": "string", "description": "Ed25519 signature (hex) over the canonical JSON of verdict"}, "key_id": {"type": "string"}, "public_key": {"type": "string"}, "verified": {"type": "boolean"}}, "required": ["verdict", "signature", "key_id"]}, "AuditRequest": {"type": "object", "properties": {"run_id": {"type": "string"}, "checkpoint_ns": {"type": "string"}, "journal": {"description": "Array of {node, effect_key, kind} or a journal string"}}, "required": ["run_id", "checkpoint_ns", "journal"]}, "RegisterRequest": {"type": "object", "properties": {"account_name": {"type": "string"}, "payer_wallet": {"type": "string", "description": "0x address that will pay"}}, "required": ["account_name", "payer_wallet"]}, "RegisterResponse": {"type": "object", "properties": {"account_id": {"type": "string"}, "claim_token": {"type": "string", "description": "Shown once; single-purpose, 24h"}, "payment_instructions": {"type": "object"}}, "required": ["account_id", "claim_token"]}, "SubscribeRequest": {"type": "object", "properties": {"account_id": {"type": "string"}, "claim_token": {"type": "string"}, "tier": {"type": "string", "enum": ["solo", "team"]}}, "required": ["account_id", "tier"]}, "TokenResponse": {"type": "object", "properties": {"account_id": {"type": "string"}, "token": {"type": "string", "description": "Shown ONCE. Only its SHA-256 hash is stored."}, "tier": {"type": "string"}, "trial": {"type": "boolean"}, "issued_at": {"type": "number"}, "expires_at": {"type": "number"}, "status": {"type": "string", "example": "active"}}, "required": ["account_id", "token", "expires_at"]}}}, "paths": {"/health": {"get": {"summary": "Liveness", "responses": {"200": {"description": "ok"}}}}, "/": {"get": {"summary": "Product descriptor: features, limits, prices, how to start", "responses": {"200": {"description": "ok"}}}}, "/keys": {"get": {"summary": "Pinned Ed25519 verdict-signing keys + encoding", "responses": {"200": {"description": "ok"}}}}, "/.well-known/x402": {"get": {"summary": "x402 payment terms for /verdict", "responses": {"200": {"description": "ok"}}}}, "/openapi.json": {"get": {"summary": "This spec", "responses": {"200": {"description": "ok"}}}}, "/llms.txt": {"get": {"summary": "Product facts in llms.txt format", "responses": {"200": {"description": "ok"}}}}, "/package": {"get": {"summary": "Download the resume_guard wheel", "responses": {"200": {"description": "wheel file"}}}}, "/register": {"post": {"summary": "Create an account (unauthenticated, rate-limited)", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RegisterRequest"}}}}, "responses": {"200": {"description": "account + claim token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RegisterResponse"}}}}, "400": {"description": "bad request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "rate limited", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/trial": {"post": {"summary": "Claim the one-time free Solo month with a claim token", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"account_id": {"type": "string"}, "claim_token": {"type": "string"}}, "required": ["account_id", "claim_token"]}}}}, "responses": {"200": {"description": "trial token issued", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TokenResponse"}}}}, "400": {"description": "invalid/expired claim or trial already used", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/subscribe": {"post": {"summary": "Pay a tier via x402 and receive/renew the account token. Send X-PAYMENT with a signed Base USDC authorization for the tier price to payTo 0xAc2E243a075fEe442e4c6864DcF880eb4e3A3862.", "parameters": [{"name": "X-PAYMENT", "in": "header", "required": true, "schema": {"type": "string"}, "description": "base64 x402 v1 payment payload"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SubscribeRequest"}}}}, "responses": {"200": {"description": "token issued / renewed", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TokenResponse"}}}}, "402": {"description": "payment required or rejected (see error field)", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "bad request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/tokens/revoke": {"post": {"summary": "Revoke a token (a token revokes itself; the operator token revokes any)", "security": [{"BearerAuth": []}], "responses": {"200": {"description": "revoked"}, "401": {"description": "unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/effects": {"post": {"summary": "Record (backfill) an effect in your account's ledger", "security": [{"BearerAuth": []}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/EffectRequest"}}}}, "responses": {"200": {"description": "recorded", "content": {"application/json": {"schema": {"type": "object", "properties": {"effect_id": {"type": "string"}, "status": {"type": "string"}}}}}}, "401": {"description": "unauthorized / expired (body names renewal)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/effects/execute": {"post": {"summary": "Guarded execution against the demo target: exactly-once; a resume injects the recorded receipt", "security": [{"BearerAuth": []}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/EffectRequest"}}}}, "responses": {"200": {"description": "receipt", "content": {"application/json": {"schema": {"type": "object", "properties": {"receipt": {"type": "object"}, "how": {"type": "string", "enum": ["executed", "injected"]}, "target_submit_calls": {"type": "integer"}}}}}}, "401": {"description": "unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/verdict": {"post": {"summary": "Signed resume verdict. Subscriber bearer token OR x402 per-verdict payment ($0.005).", "security": [{"BearerAuth": []}], "parameters": [{"name": "X-PAYMENT", "in": "header", "required": false, "schema": {"type": "string"}, "description": "base64 x402 v1 payment payload (alternative to bearer)"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerdictRequest"}}}}, "responses": {"200": {"description": "signed verdict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerdictResponse"}}}}, "402": {"description": "payment required / payment rejected", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "bad request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/audit": {"post": {"summary": "Journal-completeness audit for a run in your account", "security": [{"BearerAuth": []}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuditRequest"}}}}, "responses": {"200": {"description": "audit report with signed certificate when fully certified", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/pin": {"post": {"summary": "Pin a checkpoint discovery digest", "security": [{"BearerAuth": []}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"run_id": {"type": "string"}, "checkpoint_ns": {"type": "string"}, "discovery_pin": {"type": "string"}}, "required": ["run_id", "checkpoint_ns", "discovery_pin"]}}}}, "responses": {"200": {"description": "pinned"}, "401": {"description": "unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}}}