Documentation

API Reference

Base URL: https://captre.onrender.com/  ·  Interactive OpenAPI ↗

Paid endpoints (POST /attest, POST /revoke, POST /submit-task, POST /evaluate) require an x402-enabled HTTP client. The server returns 402 Payment Required and the client must settle USDC on Algorand before the request is fulfilled. Free endpoints work with plain curl.
Endpoints
Method Path Payment Purpose
POST /attest $0.01 USDC Create a first-claim attestation
GET /verify Free Verify by content_hash query param
GET /attestation/{id} Free Retrieve by UUID or content_hash
POST /revoke $0.01 USDC Revoke — original author only
POST /submit-task $0.01 USDC Anchor a task hash on-chain
GET /task/{id} Free Retrieve task by UUID or hash
POST /evaluate $0.01 USDC Record evaluation of an attestation
GET /evaluation/{id} Free Retrieve evaluation by UUID
Payment flow

How x402 works

01 / Client
Sends POST /attest with content_hash
02 / Middleware
Returns 402 + payment requirements
03 / Client
Signs & submits Algorand USDC tx
04 / Facilitator
Verifies settlement, issues receipt
05 / Captre
Writes box on-chain, returns attestation

Facilitator: https://facilitator.goplausible.xyz  ·  Network: mainnet

POST /attest $0.01 USDC
Create first-claim attestation

A content_hash can only ever be claimed once — revocation does not reopen it to new claimants.

Request body (JSON)
{
  "content_hash":  "sha256:abc…", // required
  "agent_id":      "my-agent",    // optional
  "output_type":   "file",        // optional
  "description":   "…",           // optional
  "model":         "gpt-4o",      // optional
  "tags":          ["v1"],        // optional
  "extra":         {}             // optional
}
Response 200
{
  "attestation": {
    "attestation_id": "a00fe88e-…",
    "author":   "GFYF3KDN…",
    "status":   "active",
    "tx_id":    "QK5ATJTD…"
  },
  "message": "Attestation created successfully"
}
402 Payment required (x402 challenge)
409 content_hash already claimed — returns existing
500 Box write failed after payment settled (retry safe)
GET /verify Free
Verify by content hash
curl example
curl "https://captre.onrender.com/verify?content_hash=sha256:YOUR_HASH"
GET /attestation/{id} Free
Retrieve by UUID or content hash

UUIDs are resolved via the on-chain id_index BoxMap. You can also pass the raw content_hash directly.

By UUID
curl "https://captre.onrender.com/attestation/a00fe88e-c4fa-4d4a-92d6-043af786e4b4"
By content hash
curl "https://captre.onrender.com/attestation/sha256%3Aabc123..."
POST /revoke $0.01 USDC
Revoke — original author only

The x402 payer address of the revoke request must exactly match the author stored in the original attestation. Revocation is permanent — the hash is never reopened.

Request body
{ "attestation_id": "a00fe88e-…" }
402 Payment required
403 Payer is not the original author
404 Attestation not found
POST /submit-task $0.01 USDC
Anchor a task hash on-chain

Register a task in TaskApp. The SHA-256 of the raw content becomes the on-chain key — only the hash is written to Algorand box storage. A task hash can only be claimed once.

Request body (JSON)
{
  "content":     "Summarise paper X",  // required — hashed on server
  "agent_id":    "my-agent",           // optional
  "description": "…",                  // optional
  "tags":        ["v1"],               // optional
  "extra":       {}                    // optional
}
Response 200
{
  "task": {
    "task_id":    "b12fe88e-…",
    "author":     "GFYF3KDN…",
    "task_hash":  "sha256:abc…",
    "tx_id":      "QK5ATJTD…"
  },
  "message": "Task submitted successfully"
}
402 Payment required
409 Task content already claimed
500 Box write failed after payment settled (retry safe)
GET /task/{id} Free
Retrieve task by UUID or task hash

Pass either the server-assigned task_id UUID or the raw sha256:… task hash.

By UUID
curl "https://captre.onrender.com/task/b12fe88e-c4fa-4d4a-92d6-043af786e4b4"
By task hash
curl "https://captre.onrender.com/task/sha256%3Aabc123..."
POST /evaluate $0.01 USDC
Record evaluation of an attestation

Write an evaluation record to LedgerApp. The evaluator identity is the x402 payer address — cryptographically proven, not self-reported. policy_hash creates an immutable on-chain commitment to the policy document used (not just a label).

Request body (JSON)
{
  "output_attestation_id": "a00fe88e-…",  // required
  "content_hash":  "sha256:abc…",         // required
  "policy_hash":   "sha256:def…",         // required — 64 hex chars
  "evaluation_result": "pass",            // pass|fail|partial|score_only
  "task_hash":     "sha256:ghi…",         // optional
  "score":         0.92,                  // optional (required for score_only)
  "notes":         "Meets all criteria"   // optional
}
Response 200
{
  "evaluation": {
    "evaluation_id": "c99ab88e-…",
    "evaluator":     "GFYF3KDN…",
    "evaluation_result": "pass",
    "policy_hash":   "sha256:def…",
    "tx_id":         "QK5ATJTD…"
  },
  "message": "Evaluation recorded successfully"
}
402 Payment required
404 output_attestation_id not found
500 Box write failed after payment settled
GET /evaluation/{id} Free
Retrieve evaluation by UUID
curl example
curl "https://captre.onrender.com/evaluation/c99ab88e-c4fa-4d4a-92d6-043af786e4b4"
Security

Author binding

The author field is always the Algorand address that paid via x402 — extracted from the signed payment transaction group. It is never the Captre service account. You cannot spoof authorship by changing a header.

The same logic applies to revocation: Captre decodes the payer address from the x402 payment payload and compares it to the stored author before submitting any on-chain write.