{ "openapi": "3.1.0", "info": { "title": "5arz Proof-of-Human API", "version": "1.2.0", "summary": "Prove a real, ID-verified, live human performed an action — and get a signed, independently verifiable credential.", "description": "5arz is the proof-of-human layer for the internet. It issues **Proof-of-Human-Fulfillment (PoHF)** credentials: ES256-signed JWTs asserting that a real, ID-verified, live human — not a bot or AI agent — performed a specific action (work, a view, a presence event, or a personhood check). Anyone can verify a credential against the public JWKS at https://api.5arz.com/.well-known/jwks.json using any standard JWT library — no 5arz SDK and no trust in 5arz required. Use it for AI training data provenance, verified human traffic / ad-fraud defense, proof-of-personhood gating for DeFi/RWA (read `sybil_checked` before gating one-per-person actions), KYC-style human checks in your product, and the fulfillment half of agentic commerce (proving a human did the work an AI agent paid for). Human verification is free at any volume, permanently — a human never pays to prove they are a human. Businesses subscribe to a monthly plan (Free / Starter $99 / Growth $499 / Scale $2,499): seals are given away generously and vendor document checks are metered. Free `arz_test_` keys verify unlimited for integration. Compatible with Verifiable Intent and the Visa Trusted Agent Protocol; settles over Agent Pay, Stripe, or USDC.\n\n**Standards (since 27 Sep 2026).** Every live personhood and fulfillment credential is also returned as `sd_jwt_vc`: an IETF SD-JWT VC (`typ: dc+sd-jwt`, draft-ietf-oauth-sd-jwt-vc) that standard verifier libraries read without any 5arz code. Issuer metadata: https://5arz.com/.well-known/jwt-vc-issuer. Revocation: each credential carries `status.status_list` pointing at an IETF Token Status List served at `GET /statuslists/{listId}` (`application/statuslist+jwt`). Pass an optional `holderJwk` (public EC P-256 key) to bind the credential to the holder, so a copied credential cannot be presented by anyone else. Legacy `pohf_jwt` fields are unchanged. Try it without an account: `GET /api/credentials/sample`.", "termsOfService": "https://5arz.com/terms", "contact": { "name": "5arz", "email": "info@5arz.com", "url": "https://5arz.com/docs" }, "license": { "name": "Proprietary — Patents pending US 63/979,052 + US 63/979,474" } }, "servers": [ { "url": "https://api.5arz.com", "description": "Production" } ], "externalDocs": { "description": "Developer docs & SDK", "url": "https://5arz.com/docs" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Billing & plans", "description": "The published plan model: read the price list, subscribe, and check your monthly allowance." }, { "name": "Auth & credits", "description": "Register an agent and manage its API key." }, { "name": "Verification", "description": "Mint signed Proof-of-Human credentials for a session, a person, or physical presence." }, { "name": "Attestation", "description": "Prove a genuine device (not an emulator) and strengthen a credential." }, { "name": "Tracking & metrics", "description": "Attach proof to on-site actions and conversions; read verified-attention analytics." }, { "name": "Tasks", "description": "Fetch and complete embeddable micro-tasks that mint credentials." }, { "name": "Partner", "description": "Convert reward points to Stars, read balances, request payouts." }, { "name": "Work marketplace", "description": "Post work and pay a verified human to do it — at a computer, or at a real place. Register, add a job budget, post. Escrow is taken when you post, so a job that cannot be paid for never reaches a worker." }, { "name": "Keys", "description": "Public keys for verifying 5arz credentials anywhere." }, { "name": "Agentic commerce", "description": "Commission verified human work and bind a verified human to a payment on any rail (OUSD, Mastercard Agent Pay, Stripe, USDC). MCP: https://api.5arz.com/mcp" }, { "name": "Index", "description": "VHH — Verified Human Hour reference rates. Free composite; licensed categories/history. https://5arz.com/vhh-index" }, { "name": "Forwards", "description": "Prepaid verified-human-hours capacity at VHH-referenced prices." }, { "name": "Interoperability", "description": "Standard credential formats, issuer metadata and revocation lists — readable with off-the-shelf libraries." } ], "paths": { "/api/agent/tasks": { "get": { "operationId": "listVerifiedHumanTasks", "summary": "List buyable verified human work", "description": "Currently-buyable verified human work tasks. Each task carries its USD price, the same price in atomic USDC units, remaining slots, supported settlement chains, and the kind of Proof-of-Human-Fulfillment receipt issued on completion. No API key. Also served at /.well-known/agent-tasks.json. Wrapped by the MCP tool list_verified_human_tasks on https://mcp.5arz.com.", "tags": [ "Verified human work" ], "security": [], "responses": { "200": { "description": "Task list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "count": { "type": "integer" }, "demo_mode": { "type": "boolean", "description": "true when settlement runs against the Base Sepolia demo facilitator instead of real USDC." }, "provenance_tag": { "type": "string" }, "verify_attestation": { "type": "string", "description": "URL template for fetching a receipt." }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "wf_support_reply_001" }, "title": { "type": "string" }, "description": { "type": "string" }, "est_minutes": { "type": "integer" }, "slots_remaining": { "type": "integer" }, "price_usd": { "type": "number", "example": 10 }, "price_usdc_atomic": { "type": "string", "example": "10000000" }, "settlement": { "type": "object", "properties": { "currency": { "type": "string", "example": "USDC" }, "chains": { "type": "array", "items": { "type": "string" }, "example": [ "base" ] } } }, "paywall_url": { "type": "string" }, "attestation_on_fulfillment": { "type": "object", "description": "Receipt kind, patent refs, provenance tag, and the receipt URL template." } } } } } } } } } } } }, "/api/agent/tasks/{task_id}/buy": { "get": { "operationId": "purchaseVerifiedHumanTask", "summary": "Buy one slot of verified human work (x402)", "description": "Buy one slot. Called with no X-PAYMENT header this returns HTTP 402 with an x402 challenge: an accepts[] array (scheme, network, maxAmountRequired, payTo, asset, resource) and a purchase_id. Settle the USDC to a listed payTo on an offered chain, then call again with X-PAYMENT and X-Purchase-Id. On success the response carries attestation_id (also in the X-Attestation-Id header) once an approved session is linked; otherwise status is settled_awaiting_fulfillment and a receipt is linked as soon as a member completes the task. No API key at any step - the payment is the authentication. Wrapped by the MCP tool purchase_verified_human_task on https://mcp.5arz.com.", "tags": [ "Verified human work" ], "security": [], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "wf_support_reply_001", "description": "Task id from GET /api/agent/tasks." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 settlement proof. Omit to receive the 402 challenge." }, { "name": "X-Purchase-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "purchase_id from the previous 402. Required when presenting an X-PAYMENT." }, { "name": "X-Agent-Key-Thumbprint", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional RFC 7638 JWK thumbprint of the buying agent key; embedded in the receipt cnf.jkt claim." } ], "responses": { "200": { "description": "Settled. Returns purchase_id, settlement {chain, tx_hash, facilitator, demo}, attestation_id (may be null), attestation_url, and status.", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "x402 payment required - the expected first response. This is the protocol working, not an error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer", "example": 1 }, "purchase_id": { "type": "string", "example": "agpur_ffad746653ff1f3d" }, "error": { "type": "string", "example": "Payment Required" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "base" }, "maxAmountRequired": { "type": "string", "example": "10000000" }, "resource": { "type": "string" }, "payTo": { "type": "string", "description": "Treasury address to settle USDC to." }, "asset": { "type": "string", "description": "USDC contract address on the named network." }, "maxTimeoutSeconds": { "type": "integer", "example": 60 }, "extra": { "type": "object", "description": "receipt_kind, the attestation_after URL template, and patent refs." } } } } } } } } }, "404": { "description": "Unknown task id." } } } }, "/api/attestations/{attestation_id}": { "get": { "operationId": "getAttestationReceipt", "summary": "Fetch a Proof-of-Human-Fulfillment receipt", "description": "Public verifier-side receipt lookup. Returns the signed packet plus verifier identity, JWKS URL, receipt shape, short SHA-256 fingerprints of the message and signature, and a how_to_verify hint. ES256 receipts expose pohf_jwt and pohf_claims; legacy HMAC v0 receipts expose eip712_packet instead. No API key. Wrapped by the MCP tool get_attestation_receipt on https://mcp.5arz.com.", "tags": [ "Verified human work" ], "security": [], "parameters": [ { "name": "attestation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Returned at fulfillment, or in the X-Attestation-Id header on the buy response." } ], "responses": { "200": { "description": "Receipt", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "attestation_id": { "type": "string" }, "issued_at_iso": { "type": "string", "format": "date-time" }, "algorithm": { "type": "string", "example": "ES256" }, "signer_key_id": { "type": "string" }, "verifier": { "type": "string" }, "jwks_url": { "type": "string", "example": "https://api.5arz.com/.well-known/jwks.json" }, "receipt_shape": { "type": "string", "enum": [ "es256_jwt", "eip712_like_hmac_v0" ] }, "pohf_jwt": { "type": "string", "description": "Compact ES256 JWS. Present when receipt_shape is es256_jwt." }, "pohf_claims": { "type": "object" }, "eip712_packet": { "type": "object", "description": "Legacy HMAC v0 receipts only." }, "fingerprints": { "type": "object" }, "patent_refs": { "type": "array", "items": { "type": "string" } }, "provenance_tag": { "type": "string" }, "how_to_verify": { "type": "string" } } } } } }, "404": { "description": "attestation_not_found - returns ok:false, the id, and a hint.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/agents/register": { "post": { "tags": [ "Auth & credits" ], "operationId": "register", "summary": "Create an API key", "description": "Self-serve registration. Returns an API key shown once. Pass `mode:\"test\"` for a free `arz_test_` sandbox key that verifies unlimited and mints credentials marked `test:true` (never treat test credentials as production proof).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "contactEmail" ], "properties": { "name": { "type": "string", "example": "Your Company" }, "contactEmail": { "type": "string", "format": "email", "example": "you@company.com" }, "mode": { "type": "string", "enum": [ "live", "test" ], "default": "live" } } } } } }, "responses": { "200": { "description": "Key created (shown once).", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "arz_live_…" }, "agentId": { "type": "string", "example": "agt_…" }, "mode": { "type": "string", "enum": [ "live", "test" ] } } } } } } } } }, "/api/billing/plans": { "get": { "tags": [ "Billing & plans" ], "operationId": "billingPlans", "summary": "The published price list (machine-readable, no auth)", "description": "Every plan, rate and allowance as JSON, so an agent can read the price list, decide and buy without a human opening a browser. Human verification is free at any volume, permanently. Plans: Free $0 (1,000 seals/mo + 10 document checks), Starter $99/mo, Growth $499/mo, Scale $2,499/mo. Mirrors https://5arz.com/pricing exactly.", "security": [], "responses": { "200": { "description": "Plan catalogue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "currency": { "type": "string" }, "human_verification": { "type": "object", "description": "Always price 0. A human never pays to prove they are a human." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "price_monthly_usd": { "type": [ "number", "null" ] }, "seals_per_month": { "type": [ "integer", "null" ], "description": "null = unlimited" }, "document_checks_included": { "type": "integer" }, "document_check_usd": { "type": [ "number", "null" ] }, "retention_days": { "type": [ "integer", "null" ] } } } }, "checkout": { "type": "object" } } } } } } } } }, "/api/billing/me": { "get": { "tags": [ "Billing & plans" ], "operationId": "billingMe", "summary": "Current plan, usage and what is left this month", "description": "Returns the caller's plan plus seals and document checks consumed in the current UTC month, and the remaining allowance. Replaces the retired prepaid credit balance.", "responses": { "200": { "description": "Plan and usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "plan": { "type": "string" }, "label": { "type": "string" }, "price_monthly_usd": { "type": [ "number", "null" ] }, "usage": { "type": "object", "properties": { "seals": { "type": "integer" }, "seals_included": { "type": [ "integer", "null" ] }, "seals_remaining": { "type": [ "integer", "null" ] }, "document_checks": { "type": "integer" }, "document_checks_included": { "type": "integer" }, "document_check_usd": { "type": [ "number", "null" ] } } }, "period_start": { "type": "integer" }, "human_verification": { "type": "string" } } } } } } } } }, "/api/billing/checkout": { "post": { "tags": [ "Billing & plans" ], "operationId": "billingCheckout", "summary": "Subscribe to a plan (Stripe checkout, or a 402 for an agent)", "description": "Omit `mode` to get a hosted Stripe Checkout URL for a human. Send `mode:\"agent\"` to get HTTP 402 with machine-readable payment requirements (x402 on Base/USDC, or the Stripe fallback), so an autonomous buyer can settle without a browser session. `plan:\"free\"` activates the Free plan with no card.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale" ] }, "mode": { "type": "string", "enum": [ "agent" ], "description": "Omit for a human checkout URL." }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Checkout created (or Free plan activated).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "plan": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" } } } } } }, "402": { "description": "mode:\"agent\" — payment requirements, no browser needed." }, "400": { "description": "Unknown plan." } } } }, "/api/agents/credits/buy": { "post": { "tags": [ "Billing & plans" ], "operationId": "buyCredits", "deprecated": true, "summary": "RETIRED — prepaid verification packs", "description": "Retired 10 Aug 2026 and now returns HTTP 410. Prepaid packs named \"growth\" 1,000 verifications for $299 while /pricing named \"Growth\" a $499/month plan — one word, two products, two prices. No pack was ever bought, so nothing was grandfathered. Use POST /api/billing/checkout { plan: 'starter' | 'growth' | 'scale' } instead; see https://5arz.com/pricing.", "responses": { "410": { "description": "Gone. Use POST /api/billing/checkout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" }, "use": { "type": "string" }, "plans": { "type": "string" } } } } } } } } }, "/api/agents/credits/balance": { "get": { "tags": [ "Auth & credits" ], "operationId": "creditsBalance", "deprecated": true, "summary": "Legacy prepaid credit balance (prepaid packs retired 10 Aug 2026 — use GET /api/billing/me)", "responses": { "200": { "description": "Balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "integer" }, "lifetimePurchased": { "type": "integer" }, "lifetimeConsumed": { "type": "integer" }, "packs": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/agents/verify": { "post": { "tags": [ "Verification" ], "operationId": "verifyHuman", "summary": "Mint a Proof-of-Human-Fulfillment credential", "description": "Attest that a verified human session performed a unit of work. Spends 1 credit. Returns a signed ES256 PoHF JWT plus quality score and tamper-evident telemetry. Returns 402 (with a buy link) if no credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId" ], "properties": { "sessionId": { "type": "string" }, "holderJwk": { "$ref": "#/components/schemas/HolderJwk" } } } } } }, "responses": { "200": { "description": "Signed credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "402": { "description": "No credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid input, including a malformed or private `holderJwk`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agents/verify-personhood": { "post": { "tags": [ "Verification" ], "operationId": "verifyPersonhood", "summary": "Mint a Proof-of-Personhood credential", "description": "Prove a real, ID-verified, live human. Spends 1 credit. This does NOT establish that the person holds only one account — the credential carries `sybil_checked`, and it is `false` wherever no duplicate check ran. Optionally bind an EVM wallet (see /api/agents/wallet/challenge) to add a `wallet` claim for on-chain isVerifiedHuman() gating.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "memberId" ], "properties": { "memberId": { "type": "string" }, "wallet": { "type": "string", "description": "EVM address (optional)" }, "walletSig": { "type": "string", "description": "EIP-191 personal_sign of the challenge (optional)" }, "walletNonce": { "type": "string" }, "holderJwk": { "$ref": "#/components/schemas/HolderJwk" } } } } } }, "responses": { "200": { "description": "Signed personhood credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Invalid input, including a malformed or private `holderJwk`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kinetic/submit": { "post": { "tags": [ "Verification" ], "operationId": "kineticSubmit", "summary": "Prove physical presence", "description": "Submit a receipt or geo-tagged photo as physical-presence evidence. Scored into a session; mint a credential via /api/agents/verify. One-time-use per photo hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "memberId", "source" ], "properties": { "memberId": { "type": "string" }, "source": { "type": "string", "enum": [ "receipt", "geo_photo" ] }, "lat": { "type": "number" }, "lng": { "type": "number" }, "photoHash": { "type": "string" } } } } } }, "responses": { "200": { "description": "Scored session." } } } }, "/api/agents/attest/challenge": { "post": { "tags": [ "Attestation" ], "operationId": "attestChallenge", "summary": "Device attestation — step 1", "description": "Returns a one-time nonce/challenge for anti-replay device attestation.", "responses": { "200": { "description": "Challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string" }, "challengeB64url": { "type": "string" } } } } } } } } }, "/api/agents/attest/verify": { "post": { "tags": [ "Attestation" ], "operationId": "attestVerify", "summary": "Device attestation — step 2", "description": "Prove a genuine device (not an emulator). Attested devices add a `device` claim to credentials.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "nonce", "subjectRef" ], "properties": { "method": { "type": "string", "enum": [ "webauthn", "play_integrity", "app_attest" ] }, "nonce": { "type": "string" }, "subjectRef": { "type": "string" } } } } } }, "responses": { "200": { "description": "Attestation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attested": { "type": "boolean" }, "assurance": { "type": "string" } } } } } } } } }, "/api/track/event": { "post": { "tags": [ "Tracking & metrics" ], "operationId": "trackEvent", "summary": "Public behavior beacon", "description": "Cookieless, sendBeacon-friendly on-site behavior tied to a verified view (`vt`). Emitted by the post-click tag.", "security": [], "responses": { "200": { "description": "Recorded." } } } }, "/api/agents/track/conversion": { "post": { "tags": [ "Tracking & metrics" ], "operationId": "trackConversion", "summary": "Server-side conversion tied to a verified view", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vt", "name" ], "properties": { "vt": { "type": "string", "description": "verified-view token" }, "name": { "type": "string", "example": "purchase" }, "value": { "type": "number" }, "currency": { "type": "string", "example": "USD" } } } } } }, "responses": { "200": { "description": "Attribution result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attributed": { "type": "boolean" } } } } } } } } }, "/api/agents/metrics": { "get": { "tags": [ "Tracking & metrics" ], "operationId": "metrics", "summary": "Verified-attention analytics", "description": "Summary + per-view rows (focus, probe, input, gaze, quality, fraud flags), each tagged with its credential id.", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Metrics." } } } }, "/api/agents/metrics/funnel": { "get": { "tags": [ "Tracking & metrics" ], "operationId": "metricsFunnel", "summary": "Verified funnel (views → landed → engaged → conversions)", "responses": { "200": { "description": "Funnel with rates + value." } } } }, "/api/tasks/next": { "get": { "tags": [ "Tasks" ], "operationId": "tasksNext", "summary": "Fetch an embeddable micro-task", "security": [], "parameters": [ { "name": "site", "in": "query", "schema": { "type": "string" }, "description": "agentId" } ], "responses": { "200": { "description": "A task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object" } } } } } } } } }, "/api/tasks/complete": { "post": { "tags": [ "Tasks" ], "operationId": "tasksComplete", "summary": "Submit a task completion", "description": "Public. A verified completion (answer + attention) mints a PoHF via /api/agents/verify.", "security": [], "responses": { "200": { "description": "Completion recorded." } } } }, "/api/agents/wallet/challenge": { "post": { "tags": [ "Verification" ], "operationId": "walletChallenge", "summary": "On-chain personhood — get a message to sign", "responses": { "200": { "description": "Nonce + message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/agents/webhooks": { "post": { "tags": [ "Auth & credits" ], "operationId": "registerWebhook", "summary": "Register a push webhook", "description": "HMAC-signed (X-5arz-Signature). Fires events such as personhood.wallet_bound.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Webhook registered (signingSecret shown once).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "signingSecret": { "type": "string" } } } } } } } } }, "/api/partner/points/convert": { "post": { "tags": [ "Partner" ], "operationId": "partnerPointsConvert", "summary": "Convert reward points to Stars", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userRef", "points" ], "properties": { "userRef": { "type": "string" }, "points": { "type": "number" } } } } } }, "responses": { "200": { "description": "Idempotent. New balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number" } } } } } } } } }, "/api/partner/payout/request": { "post": { "tags": [ "Partner" ], "operationId": "partnerPayoutRequest", "summary": "Queue a Stars → cash payout", "description": "Reviewed; no auto-transfer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userRef", "stars" ], "properties": { "userRef": { "type": "string" }, "stars": { "type": "number" } } } } } }, "responses": { "200": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "status": { "type": "string" } } } } } } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Keys" ], "operationId": "jwks", "summary": "Public keys", "description": "Verify any 5arz credential's ES256 signature against these keys — no 5arz software required.", "security": [], "responses": { "200": { "description": "JWK Set.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/workflows/available": { "get": { "operationId": "listVerifiedWork", "summary": "List commissionable verified-work tasks.", "responses": { "200": { "description": "OK" } }, "tags": [ "Agentic commerce" ] } }, "/api/agents/order": { "post": { "operationId": "commissionWork", "summary": "Commission verified human work.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskType": { "type": "string" }, "quantity": { "type": "number" }, "maxPriceUsd": { "type": "number" } }, "required": [ "taskType", "quantity" ] } } } }, "responses": { "200": { "description": "Order created" }, "401": { "description": "Auth required" } }, "tags": [ "Agentic commerce" ] } }, "/api/agents/bind-transaction": { "post": { "operationId": "bindHumanToPayment", "summary": "Bind a verified human to a Tempo/OUSD/Agent Pay/Stripe/USDC payment; returns a signed credential. Pass test:true to try without a live payment.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentRef": { "type": "string" }, "sessionId": { "type": "string" }, "memberId": { "type": "string" }, "workRef": { "type": "string" }, "test": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Signed binding credential" }, "400": { "description": "Missing payment/human anchor" }, "401": { "description": "Auth required" } }, "tags": [ "Agentic commerce" ] } }, "/api/index": { "get": { "tags": [ "Index" ], "operationId": "indexCatalog", "summary": "VHH index catalog — published codes with latest final epoch (free, cached).", "security": [], "responses": { "200": { "description": "Catalog" } } } }, "/api/index/vhh": { "get": { "tags": [ "Index" ], "operationId": "indexVhh", "summary": "VHH composite. Free: latest final epoch, ES256-signed (verify against /.well-known/jwks.json). With an agent API key: current MTD + categories + ?history=1.", "security": [], "responses": { "200": { "description": "Signed epoch" }, "403": { "description": "Licensed tier requires API key" } } } }, "/api/index/{code}": { "get": { "tags": [ "Index" ], "operationId": "indexByCode", "summary": "Any VHH_* category series (licensed — agent API key).", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "example": "VHH_content_mod" } ], "responses": { "200": { "description": "Series" }, "403": { "description": "License required" } } } }, "/api/forwards/order": { "post": { "tags": [ "Forwards" ], "operationId": "forwardOrder", "summary": "Order prepaid verified-human-hours capacity (category, hours, month) at a VHH-referenced price. Intake only — countersigned service agreement + Stripe invoice follow. Not transferable, not resellable, not cash-settled.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "company", "email", "hours", "month" ], "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "category": { "type": "string" }, "hours": { "type": "number" }, "month": { "type": "string", "example": "2026-08" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Order received with capacity assessment + indicative price" } } } }, "/statuslists/{listId}": { "get": { "tags": [ "Interoperability" ], "operationId": "getTokenStatusList", "summary": "IETF Token Status List (revocation)", "description": "Signed status list referenced by `status.status_list.uri` in each `sd_jwt_vc`. One bit per credential (1 = revoked), zlib-compressed, LSB-first, per draft-ietf-oauth-status-list. The whole list is fetched, so 5arz never learns which credential a verifier checked. Cacheable (`ttl` 900 s).", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed status list token.", "content": { "application/statuslist+jwt": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed list id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown list." } } } }, "/api/credentials/sample": { "get": { "tags": [ "Interoperability" ], "operationId": "getSampleCredential", "summary": "Sample credential (public, no key)", "description": "A clearly marked sample credential in both forms (`jwt` and `sd_jwt_vc`) with verification instructions, so integrators can test a verifier before buying credits. Not valid as production proof.", "responses": { "200": { "description": "Sample credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sample": { "type": "boolean" }, "jwt": { "type": "string" }, "sd_jwt_vc": { "type": "string" }, "vct": { "type": "string" }, "jwks_url": { "type": "string" }, "how_to_verify": {}, "claims": { "type": "object" } } } } } } } } }, "/.well-known/jwt-vc-issuer": { "get": { "tags": [ "Interoperability" ], "operationId": "getIssuerMetadata", "summary": "SD-JWT VC issuer metadata", "servers": [ { "url": "https://5arz.com" } ], "description": "Issuer metadata for `iss: https://5arz.com`: points verifiers at the signing keys.", "responses": { "200": { "description": "Issuer metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "jwks_uri": { "type": "string" } } } } } } } } }, "/api/agents/keys": { "get": { "tags": [ "Keys" ], "operationId": "listSubKeys", "summary": "List this account's sub-keys", "security": [ { "bearerAuth": [] } ], "description": "One business, many agents: list the scoped sub-keys minted under this account's primary key. Sub-keys cannot call this.", "responses": { "200": { "description": "Sub-keys (prefix only, never the key).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key_prefix": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "last_used_at": { "type": [ "integer", "null" ] }, "revoked_at": { "type": [ "integer", "null" ] } } } } } } } } }, "401": { "description": "No valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Called with a sub-key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Keys" ], "operationId": "mintSubKey", "summary": "Mint a sub-key for one of your agents", "security": [ { "bearerAuth": [] } ], "description": "Mint a key for an individual agent or integration. It shares the account's plan, credits, billing and mode (a test account can only mint test keys) and cannot manage keys. Shown once.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } } } } }, "responses": { "200": { "description": "New sub-key (store it now).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "keyId": { "type": "string" }, "apiKey": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "label": { "type": [ "string", "null" ] }, "warning": { "type": "string" } } } } } }, "401": { "description": "No valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Called with a sub-key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agents/keys/{keyId}": { "delete": { "tags": [ "Keys" ], "operationId": "revokeSubKey", "summary": "Revoke a sub-key", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "keyId": { "type": "string" }, "status": { "type": "string", "const": "revoked" } } } } } }, "401": { "description": "No valid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Called with a sub-key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown or already revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/start": { "get": { "tags": [ "Work marketplace" ], "operationId": "publicStart", "summary": "How to connect, in three calls", "description": "Unauthenticated. Returns the whole integration path — register, add a job budget, post work — plus `liveRails`, which reports which rails are currently open. Start here: it is the only call you need before you have a key.", "security": [], "responses": { "200": { "description": "Integration guide and live rail state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "what5arzIs": { "type": "string" }, "whoCanConnect": { "type": "object", "description": "The three kinds of poster: bots, businesses, people." }, "connectInThreeCalls": { "type": "array", "items": { "type": "object" } }, "liveRails": { "type": "object", "description": "Which rails are open right now. A rail reported false is built but not open.", "properties": { "deskJobs": { "type": "boolean" }, "fieldJobs": { "type": "boolean" }, "selfServeFunding": { "type": "boolean" }, "personToPerson": { "type": "boolean" }, "buyStars": { "type": "boolean" } } }, "whatWeShowYouAboutWorkers": { "type": "string", "description": "A pseudonymous reference and reputation. Never the worker's identity." } } } } } } } } }, "/api/partner/account": { "get": { "tags": [ "Work marketplace" ], "operationId": "partnerAccount", "summary": "Your job budget, limits and what to do next", "description": "One call for the whole picture: available and committed Stars, lifetime funded and spent, per-job and daily caps, how many submissions are waiting on your review, and a `nextStep` string.\n\n*Available* funds new jobs; *committed* is escrow already held against open jobs. Stars are the unit job budgets and worker pay are denominated in.\n\nThe budget belongs to your **company**, not to the key. Two keys at one business share one balance.", "responses": { "200": { "description": "Account, budget, limits and activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/partner/topup": { "post": { "tags": [ "Work marketplace" ], "operationId": "partnerTopup", "summary": "Buy job credits by card", "description": "Returns a payment link. Your balance rises when the payment clears, usually within seconds.\n\nJob credits pay workers. They are **not refundable to your card and cannot be cashed out** — there is no path from this balance to anything but worker pay. A top-up of N Stars is charged as N USD.\n\nThis rail is feature-gated and may be switched off. Check `liveRails` at `GET /api/public/start` before integrating; a 503 means the rail is built but not open, not that your request was wrong.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stars" ], "properties": { "stars": { "type": "integer", "minimum": 25, "maximum": 5000, "example": 100, "description": "Stars to buy. A top-up of N Stars is charged as N USD at checkout." }, "successUrl": { "type": "string", "format": "uri", "description": "Optional. Must be a 5arz.com URL; anything else is ignored." }, "cancelUrl": { "type": "string", "format": "uri", "description": "Optional. Must be a 5arz.com URL." } } } } } }, "responses": { "200": { "description": "Checkout link created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checkoutUrl": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" }, "stars": { "type": "integer" }, "amountUsd": { "type": "number" } } } } } }, "400": { "description": "stars outside the allowed range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Self-serve funding is not open yet — email andre@thatislumi.com to be funded directly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/partner/topup/{sessionId}": { "get": { "tags": [ "Work marketplace" ], "operationId": "partnerTopupStatus", "summary": "Did my payment land?", "description": "Status of one top-up, plus your current available balance.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Top-up status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "paid" ] }, "availableStars": { "type": "integer" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No top-up with that id on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/partner/jobs/config": { "get": { "tags": [ "Work marketplace" ], "operationId": "partnerJobsConfig", "summary": "What you are allowed to post, and your webhook", "description": "Your limits and current budget, and where job events are delivered. POST the same path to register a callback URL.", "responses": { "200": { "description": "Limits, budget and webhook target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Work marketplace" ], "operationId": "partnerJobsSetWebhook", "summary": "Register a webhook for job events", "description": "Events are signed `X-5arz-Signature: sha256=`. **Verify that signature before trusting a payload.** If you would rather poll, use `GET /api/partner/jobs/events` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhookUrl" ], "properties": { "webhookUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Webhook registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/partner/jobs": { "post": { "tags": [ "Work marketplace" ], "operationId": "postPartnerJob", "summary": "Post desk work for a verified human", "description": "Work done at a computer. Escrow is taken from your job budget at post time, so a job you cannot pay for never reaches a worker.\n\n**Idempotent on `externalRef`.** Send your own reference and a retry returns the existing job with `duplicate: true` rather than posting twice — this matters more than usual, because a duplicate here is a duplicate payment obligation.\n\nThis rail is feature-gated and may be switched off. Check `liveRails` at `GET /api/public/start` before integrating; a 503 means the rail is built but not open, not that your request was wrong.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "description", "bidStars" ], "properties": { "title": { "type": "string", "example": "Transcribe a 12-minute interview" }, "description": { "type": "string" }, "bidStars": { "type": "integer", "minimum": 2, "example": 15 }, "category": { "type": "string" }, "deliveryDays": { "type": "integer" }, "skills": { "type": "array", "items": { "type": "string" } }, "externalRef": { "type": "string", "description": "Your own id. Makes the post idempotent." }, "meta": { "type": "object", "description": "Opaque; echoed back on events." } } } } } }, "responses": { "201": { "description": "Job posted and escrowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "200": { "description": "Duplicate externalRef — the existing job is returned with duplicate:true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough budget. Top up at POST /api/partner/topup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Desk jobs are not open yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Work marketplace" ], "operationId": "listPartnerJobs", "summary": "List your desk jobs", "description": "Your jobs only. Workers appear as a pseudonymous reference.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Your jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/partner/jobs/events": { "get": { "tags": [ "Work marketplace" ], "operationId": "pullPartnerJobEvents", "summary": "Pull job events instead of receiving them", "description": "Replay queue for every job event on your account, for when you would rather poll than run a webhook endpoint, or need to catch up after an outage.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Events, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "No or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/config": { "get": { "tags": [ "Work marketplace" ], "operationId": "fieldJobsConfig", "summary": "What a field job is, and what verification does and does not prove", "description": "Unauthenticated. Limits, the three kinds of poster, the verification signal list, and the honest statement of what those signals mean. Read this before posting field work.", "security": [], "responses": { "200": { "description": "Capabilities, limits and verification policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "enabled": { "type": "boolean" }, "personPostingEnabled": { "type": "boolean" }, "limits": { "type": "object" }, "verification": { "type": "object", "description": "Signal list, modes, and the honesty statement: a confidence score, never proof of authenticity." } } } } } } } } }, "/api/field-jobs": { "post": { "tags": [ "Work marketplace" ], "operationId": "postFieldJob", "summary": "Pay a human to go somewhere and photograph it", "description": "You set a location, a radius, what the photo must show and a bounty. We geofence it, collect photos with GPS, dwell time and device motion, run verification, and pay on your approval.\n\nEscrow is taken at post time for every slot (`bountyStars × maxClaims`). Unclaimed and rejected slots are released back to you automatically.\n\n**`autoAcceptScore` defaults to 0, which means a human reviews every submission.** A value below 60 is refused. Set it only once you have watched real scores.\n\nIdempotent on `externalRef`.\n\nThis rail is feature-gated and may be switched off. Check `liveRails` at `GET /api/public/start` before integrating; a 503 means the rail is built but not open, not that your request was wrong.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "instructions", "lat", "lng", "bountyStars" ], "properties": { "title": { "type": "string", "example": "Photograph the storefront" }, "instructions": { "type": "string", "description": "What the worker must do. Shown to them verbatim." }, "lat": { "type": "number", "example": 34.0492 }, "lng": { "type": "number", "example": -118.2622 }, "radiusM": { "type": "integer", "default": 120, "minimum": 10, "maximum": 5000 }, "bountyStars": { "type": "integer", "minimum": 2, "maximum": 200, "example": 8 }, "maxClaims": { "type": "integer", "default": 1, "maximum": 100, "description": "How many workers may complete it. Escrow covers all of them." }, "shotsRequired": { "type": "integer", "default": 1, "maximum": 6 }, "subjectName": { "type": "string", "description": "What the photo must show. Used by the vision check." }, "subjectAddress": { "type": "string" }, "shotSpecs": { "type": "object", "description": "Optional per-shot requirements." }, "verifyMode": { "type": "string", "enum": [ "off", "standard", "strict" ], "default": "standard" }, "autoAcceptScore": { "type": "integer", "default": 0, "description": "0 = a human reviews every submission. Otherwise 60–100." }, "expiresAt": { "type": "integer", "description": "ms epoch. Defaults to 14 days." }, "externalRef": { "type": "string" }, "memberId": { "type": "string", "description": "Only for a person posting with a member session, not an API key." } } } } } }, "responses": { "201": { "description": "Job posted, escrow held.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "200": { "description": "Duplicate externalRef — existing job returned with duplicate:true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid coordinates, bounty out of range, or autoAcceptScore between 1 and 59.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Send an API key, or a member session with memberId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough budget for bountyStars × maxClaims.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Field jobs are not open yet, or person-posting needs P2P_ENABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Work marketplace" ], "operationId": "listFieldJobs", "summary": "List your field jobs", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "memberId", "in": "query", "schema": { "type": "string" }, "description": "Only when listing as a person rather than with an API key." } ], "responses": { "200": { "description": "Your field jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}": { "get": { "tags": [ "Work marketplace" ], "operationId": "getFieldJob", "summary": "One job, with every claim and its proof bundle", "description": "Each claim carries the GPS reading, dwell time, motion score, photo keys and the verification verdict. The worker appears as `workerRef` — a pseudonymous reference. You are buying a photograph and evidence, not a person's identity.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job, escrow and claims.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not your job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}/submissions": { "get": { "tags": [ "Work marketplace" ], "operationId": "getFieldJobSubmissions", "summary": "The photo evidence and the verification signals", "description": "Per photo: a SHA-256 fingerprint, real dimensions and type read from the bytes, and the EXIF the camera wrote — make, model, capture time, GPS, and any editing software that touched the file. Per claim: the score, the recommendation and every individual signal with its reasoning.\n\n**Scores measure how far the evidence agrees with what you asked for. They are not proof of authenticity.** A signal that could not run scores zero rather than neutral, so a photo stripped of metadata cannot reach a high score; `maxAchievable` tells you the ceiling that submission was working against.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photos, EXIF facts and verification verdicts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not your job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}/photo": { "get": { "tags": [ "Work marketplace" ], "operationId": "getFieldJobPhoto", "summary": "Fetch one submitted photo", "description": "Returns the image bytes. The key must belong to a claim on this job, so you can only ever read photos from work you paid for.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The r2Key from GET /api/field-jobs/{jobId}/submissions." } ], "responses": { "200": { "description": "The image.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "That photo is not on this job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}/approve": { "post": { "tags": [ "Work marketplace" ], "operationId": "approveFieldJobClaim", "summary": "Accept a submission and pay the worker", "description": "Pays the bounty into the worker's balance, subject to the settlement hold.\n\nIf verification recommends rejecting the submission, this returns 409 and you must send `overrideRejection: true` to pay anyway. That is deliberate: paying past a recommended rejection should be a decision, not a reflex.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "claimId" ], "properties": { "claimId": { "type": "string" }, "note": { "type": "string" }, "overrideRejection": { "type": "boolean", "default": false }, "memberId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Paid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "starsPaid": { "type": "integer" }, "feeStars": { "type": "integer" }, "workerReceivesCashableAt": { "type": "integer", "description": "ms epoch when the payout matures for the worker." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Claim not on this job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already reviewed, or verification recommends rejection and no override was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}/reject": { "post": { "tags": [ "Work marketplace" ], "operationId": "rejectFieldJobClaim", "summary": "Reject a submission and release the escrow", "description": "Frees the slot for another worker and returns the escrow to you. A reason of at least 10 characters is required — the worker is told why.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "claimId", "reason" ], "properties": { "claimId": { "type": "string" }, "reason": { "type": "string", "minLength": 10 }, "memberId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Rejected, escrow released.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Reason missing or too short.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No submitted claim with that id on this job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/field-jobs/{jobId}/cancel": { "post": { "tags": [ "Work marketplace" ], "operationId": "cancelFieldJob", "summary": "Cancel a job and refund unworked slots", "description": "Refuses with 409 while workers have the job claimed or submitted, so you review their work first. Send `force: true` to cancel only the unclaimed slots.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "default": false }, "memberId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cancelled, unworked slots refunded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Work in progress and force was not set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "arz_live_… / arz_test_…", "description": "Authorization: Bearer . Required on all endpoints except register, public track/tasks beacons, and jwks." } }, "schemas": { "Credential": { "type": "object", "description": "A Proof-of-Human credential response.", "properties": { "pohf_jwt": { "type": "string", "description": "ES256-signed compact JWT. Verify against the public JWKS." }, "verified": { "type": "boolean" }, "quality": { "type": "number", "description": "0–1 human-attention quality score" }, "credentialId": { "type": "string" }, "sd_jwt_vc": { "type": "string", "description": "The same claims as an IETF SD-JWT VC (header typ `dc+sd-jwt`, serialization ends with `~`). Verify with any SD-JWT VC library against the issuer metadata at https://5arz.com/.well-known/jwt-vc-issuer. Carries `status.status_list` for revocation and `cnf.jwk` when `holderJwk` was supplied." }, "sd_jwt_vc_hint": { "type": "string", "description": "Human-readable pointer to the standards and key locations." }, "sd_jwt_vc_error": { "type": "string", "description": "Present only if the standard form could not be produced; the legacy credential is still valid." } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string" }, "buy": { "type": "string", "format": "uri", "description": "Present on 402 — link to buy credits." } } }, "HolderJwk": { "type": "object", "description": "PUBLIC holder key (EC P-256). A key containing the private part `d` is refused with 400, never stripped.", "required": [ "kty", "crv", "x", "y" ], "properties": { "kty": { "type": "string", "const": "EC" }, "crv": { "type": "string", "const": "P-256" }, "x": { "type": "string", "description": "base64url, 43 chars" }, "y": { "type": "string", "description": "base64url, 43 chars" } } } } } }