Create, verify, and poll ephemeral receipts for AI agent workflows.
Pass your API key as a Bearer token:
Authorization: Bearer ak_live_...
Get a free key by calling POST /v1/auth/signup. Verification endpoints are public.
| Limit | Value |
|---|---|
| Rate limit | 60 req/min per API key |
| Free tier | 500 receipts/month |
| Max body | 16 KB |
| Max summary | 280 chars |
| Max payload | 4 KB |
Create a verifiable receipt when something happens in your agent workflow.
| Field | Type | Description | |
|---|---|---|---|
| type | string | required | action, approval, handshake, resume, or failure |
| status | string | required | Freeform status (e.g. "success", "pending") |
| summary | string | required | Human-readable summary, max 280 chars |
| payload | object | Structured JSON data, max 4KB | |
| ref | object | run_id, agent_id, action_id, workflow_id, session_id | |
| expires_in | integer | TTL in seconds, 60–86400. Default 86400 | |
| idempotency_key | string | Prevents duplicate creation on retry | |
| audience | string | "human" for enriched social cards |
POST /v1/receipts
Authorization: Bearer ak_live_abc123
Content-Type: application/json
{
"type": "action",
"status": "success",
"summary": "Refund of $42.00 to customer #8812",
"payload": {"amount": 42.00, "currency": "USD"},
"idempotency_key": "refund-8812-2026-03-23"
}
{
"receipt_id": "rct_k7x9m2p4",
"type": "action",
"status": "success",
"summary": "Refund of $42.00 to customer #8812",
"verify_url": "https://proofslip.ai/verify/rct_k7x9m2p4",
"created_at": "2026-03-23T12:00:00Z",
"expires_at": "2026-03-24T12:00:00Z",
"is_terminal": true
}
Verify a receipt and retrieve its full data. Returns HTML by default, or JSON with ?format=json.
GET /v1/verify/rct_k7x9m2p4?format=json
{
"receipt_id": "rct_k7x9m2p4",
"valid": true,
"type": "action",
"status": "success",
"summary": "Refund of $42.00 to customer #8812",
"payload": {"amount": 42.00, "currency": "USD"},
"created_at": "2026-03-23T12:00:00Z",
"expires_at": "2026-03-24T12:00:00Z",
"expired": false,
"is_terminal": true
}
Returns 404 if the receipt is not found, expired, or deleted.
Lightweight status poll. Returns only status fields — no summary, payload, or ref. Ideal for polling loops.
{
"receipt_id": "rct_k7x9m2p4",
"status": "success",
"is_terminal": true,
"next_poll_after_seconds": null,
"expires_at": "2026-03-23T13:00:00Z"
}
If is_terminal is true, stop polling. If false, wait next_poll_after_seconds before retrying.
Get a free API key. Save it immediately — it cannot be retrieved later.
| Field | Type | Description | |
|---|---|---|---|
| string | required | Your email address | |
| source | string | "api" returns key directly, "web" emails it |
POST /v1/auth/signup
Content-Type: application/json
{"email": "dev@example.com", "source": "api"}
{
"api_key": "ak_live_abc123def456",
"tier": "free",
"message": "Save this key - it cannot be retrieved later."
}
| Type | Use Case |
|---|---|
| action | Record a completed event (refund, deploy, notification) |
| approval | Gate an action on a human or agent decision |
| handshake | Coordinate between two agents before either acts |
| resume | Bookmark a safe continuation point in a pipeline |
| failure | Structured error record with bounded retry window |
All errors return JSON:
{"error": "error_code", "message": "Human-readable description", "request_id": "req_..."}
| Code | HTTP | Meaning |
|---|---|---|
| validation_error | 400 | Missing or invalid field |
| unauthorized | 401 | Missing or invalid API key |
| not_found | 404 | Receipt not found, expired, or deleted |
| idempotency_conflict | 409 | Same key, different body |
| rate_limited | 429 | Too many requests |
| internal_error | 500 | Unexpected server error |
Use ProofSlip as a tool in Claude, Cursor, or any MCP-compatible client:
npx -y @proofslip/mcp-server
Tools: create_receipt, verify_receipt, check_status
ProofSlip exposes multiple discovery endpoints for agents and tools:
| Endpoint | Format | Purpose |
|---|---|---|
| /llms.txt | Plain text | LLM context summary |
| /llms-full.txt | Plain text | Complete API reference for LLMs |
| /.well-known/openapi.json | JSON | OpenAPI 3.1 spec |
| /.well-known/ai-plugin.json | JSON | ChatGPT plugin manifest |
| /.well-known/mcp.json | JSON | MCP server discovery |
| /.well-known/agent.json | JSON | Agent protocol discovery |