{"openapi":"3.1.0","info":{"title":"Action Layer agent API","version":"0.4.0","description":"Human-work API for AI agents and robotics workflows: onboarding, operator-reviewed requests, owner permissions, spending allowances and verified delivery. Availability is controlled by deployment capabilities."},"servers":[{"url":"https://actionlayer-production.vercel.app"}],"x-onboarding-enabled":true,"x-jobs-enabled":false,"x-wallets-enabled":false,"x-payments-enabled":false,"x-environment":"live","paths":{"/api/v1/workers":{"get":{"summary":"Discover opted-in, approved, available human workers. Requires agent:read. City matching is exact; service radius is informational. No reservation or fixed price is implied.","security":[{"AgentCredential":[]}],"parameters":[{"name":"capability","in":"query","schema":{"type":"string","enum":["PHONE","PHOTOS","DELIVERY","ERRAND","RESEARCH","DIGITAL","DOCUMENT","PROFESSIONAL","CUSTOM"]}},{"name":"city","in":"query","schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"skill","in":"query","schema":{"type":"string","minLength":2,"maxLength":50}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":12}}],"responses":{"200":{"description":"Public profiles only, with counts of verified completed work.","content":{"application/json":{"schema":{"type":"object","required":["workers","total","page","limit","next_action"],"properties":{"workers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"headline":{"type":"string"},"bio":{"type":"string"},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"service_radius_km":{"type":"integer"},"capabilities":{"type":"array","items":{"type":"string","enum":["PHONE","PHOTOS","DELIVERY","ERRAND","RESEARCH","DIGITAL","DOCUMENT","PROFESSIONAL","CUSTOM"]}},"skills":{"type":"array","items":{"type":"string"}},"completed_jobs":{"type":"integer"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"matching":{"const":"city_exact"},"assignment":{"const":"operator_managed"},"pricing":{"const":"quoted_per_job"},"availability":{"const":"snapshot_not_reserved"},"job_submission_enabled":{"type":"boolean"},"next_action":{"type":"object"}}}}}},"default":{"description":"Structured API error; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/services":{"get":{"summary":"Read enabled services, requirements JSON schemas, supported cities and deadline limits.","security":[],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs":{"get":{"summary":"List your latest jobs. Requires jobs:read.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}]},"post":{"summary":"Request operator review and a quote. Requires jobs:create. Retry the same body with the same key.","security":[{"AgentCredential":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJob"}}}},"responses":{"201":{"description":"Created or recovered the same request.","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"default":{"description":"Structured API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}]}},"/api/v1/jobs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read your job, quote version, buyer messages, funding status and next_action. Requires jobs:read.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Clarify a NEEDS_INFO request using complete requirements; retain service and budget. Requires jobs:create.","security":[{"AgentCredential":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJob"}}}},"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Cancel an unfunded request; release an unstarted reservation. Never refunds escrow. Requires jobs:create.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/accept":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Accept the exact quote version and amount. Atomically reserves per-job and UTC daily allowance. Safe to repeat. Requires jobs:create.","security":[{"AgentCredential":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptQuote"}}}},"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/fund":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Advance accepted funding when deployment capabilities permit it. Repeat every 10 seconds until funded or needs_review. Requires jobs:create.","security":[{"AgentCredential":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundJob"}}}},"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/deliverables":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List operator-verified delivery. Requires jobs:read and ownership.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/deliverables/{fileId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Download an approved file as binary; send the agent bearer credential. Never public.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Private attachment.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Structured API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents/{id}/wallet":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read wallet availability, address, grant and balances on its recorded chain. Owner only.","security":[{"PrivyAccessToken":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Explicitly authorize a dedicated user-owned wallet with restricted ACP signing when wallet operations are available. Requires owner JWT.","security":[{"PrivyAccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletConsent"}}}},"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Stop application spending and detach the Privy signer. Already broadcast transactions may settle. Retry if signer_removal_pending.","security":[{"PrivyAccessToken":[]}],"responses":{"200":{"description":"Success. Follow next_action and funding.status.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Structured API error; honor Retry-After. Never infer payment from an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents":{"post":{"summary":"Register a pending agent. Save the returned secrets immediately; registration is not idempotent.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent","credential","claim_token","approval_url","mode"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"credential":{"type":"string","description":"Secret agent bearer credential, shown only once."},"claim_token":{"type":"string","description":"Private one-use approval token."},"approval_url":{"type":"string","format":"uri"},"mode":{"const":"live"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/me":{"get":{"summary":"Read your agent and its next onboarding action. Available to a pending agent.","security":[{"AgentCredential":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents":{"get":{"summary":"List your authorized agents (maximum 100 active agents per owner).","security":[{"PrivyAccessToken":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents/preview":{"post":{"summary":"Review an unexpired approval request before consenting.","security":[{"PrivyAccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents/authorize":{"post":{"summary":"Consume a one-use claim and approve its permissions and allowances.","security":[{"PrivyAccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Authorization"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Immediately revoke an agent you own. Safe to repeat.","security":[{"PrivyAccessToken":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/agents/{id}/credential":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Replace an owned agent credential, invalidating the previous credential immediately. Save the returned secret.","security":[{"PrivyAccessToken":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"credential":{"type":"string"}}}}}},"400":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured API error. Honor Retry-After on 429 and temporary 503 responses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"AgentCredential":{"type":"http","scheme":"bearer","description":"The al_agent_ credential from registration or owner rotation."},"PrivyAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An unexpired Privy access token issued for this deployment’s Privy app. Never an agent key."}},"schemas":{"CreateJob":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"offering":{"type":"string","enum":["phone_task","site_photos","remote_task","custom_human_task"]},"requirements":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"max_budget_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000},"preferred_worker_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["offering","requirements","max_budget_cents"],"additionalProperties":false,"description":"Requirements must match the selected service schema from GET /api/v1/services. JSON body at most 8 KB. UTC deadline 30 minutes to 7 days ahead."},"AcceptQuote":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quote_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000},"mode":{"type":"string","const":"live"}},"required":["quote_version","amount_cents","mode"],"additionalProperties":false},"FundJob":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"mode":{"type":"string","const":"live"}},"required":["mode"],"additionalProperties":false},"WalletConsent":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"consent":{"type":"string","const":"authorize_restricted_job_funding"}},"required":["consent"],"additionalProperties":false},"Requirements_phone_task":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":150},"instructions":{"type":"string","minLength":3,"maxLength":10000},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"verificationRequirements":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":3,"maxLength":500}},"attachments":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":2000,"format":"uri"}},"company":{"type":"string","minLength":2,"maxLength":200},"contact":{"type":"string","minLength":3,"maxLength":200},"objective":{"type":"string","minLength":3,"maxLength":10000},"requestedOutcome":{"type":"string","minLength":3,"maxLength":10000},"country":{"type":"string","minLength":2,"maxLength":80},"timeWindow":{"type":"string","minLength":3,"maxLength":200}},"required":["title","instructions","deadline","verificationRequirements","attachments","company","contact","objective","requestedOutcome","country","timeWindow"],"additionalProperties":false},"Requirements_site_photos":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":150},"instructions":{"type":"string","minLength":3,"maxLength":10000},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"verificationRequirements":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":3,"maxLength":500}},"attachments":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":2000,"format":"uri"}},"address":{"type":"string","minLength":5,"maxLength":300},"city":{"type":"string","minLength":2,"maxLength":100},"country":{"type":"string","minLength":2,"maxLength":80},"photoCount":{"type":"integer","minimum":1,"maximum":20},"shotInstructions":{"type":"string","minLength":3,"maxLength":10000}},"required":["title","instructions","deadline","verificationRequirements","attachments","address","city","country","photoCount","shotInstructions"],"additionalProperties":false},"Requirements_remote_task":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":150},"instructions":{"type":"string","minLength":3,"maxLength":10000},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"verificationRequirements":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":3,"maxLength":500}},"attachments":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":2000,"format":"uri"}},"outputFormat":{"type":"string","enum":["PDF","Images","Text","Document","Other"]},"workType":{"default":"RESEARCH","type":"string","enum":["RESEARCH","DIGITAL"]},"requiredSkills":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":80}}},"required":["title","instructions","deadline","verificationRequirements","attachments","outputFormat","workType","requiredSkills"],"additionalProperties":false},"Requirements_custom_human_task":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":150},"instructions":{"type":"string","minLength":3,"maxLength":10000},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"verificationRequirements":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":3,"maxLength":500}},"attachments":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":2000,"format":"uri"}},"location":{"type":"string","maxLength":300},"requiredSkills":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":80}},"maxBudgetCents":{"type":"integer","exclusiveMinimum":0,"maximum":10000000}},"required":["title","instructions","deadline","verificationRequirements","attachments","requiredSkills","maxBudgetCents"],"additionalProperties":false},"Job":{"type":"object","required":["id","status","mode","quote","funding","next_action"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"status":{"type":"string"},"mode":{"const":"live"},"max_budget_cents":{"type":"integer"},"deadline":{"type":"string","format":"date-time"},"quote":{"type":["object","null"],"properties":{"version":{"type":"integer"},"amount_cents":{"type":"integer"},"currency":{"const":"USD"},"payment_asset":{"type":"string","description":"Settlement asset specified by the verified quote configuration."},"chain_id":{"type":"integer","description":"Recorded job chain. Historical records retain their original chain."},"network_fees_included":{"const":false}}},"funding":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"enum":["reserved","processing","funded","cancelled","needs_review"]},"mode":{"const":"live"},"amount_cents":{"type":"integer"},"confirmed_at":{"type":["string","null"]}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"created_at":{"type":"string"}}}},"next_action":{"type":"object","properties":{"type":{"type":"string"},"poll_after_seconds":{"const":10}}}}},"Registration":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80}},"required":["name"],"additionalProperties":false},"Claim":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"claim_token":{"type":"string","pattern":"^al_claim_[A-Za-z0-9_-]{43}$"}},"required":["agent_id","claim_token"],"additionalProperties":false},"Authorization":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"claim_token":{"type":"string","pattern":"^al_claim_[A-Za-z0-9_-]{43}$"},"scopes":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["agent:read","jobs:read","jobs:create"]}},"max_job_cents":{"type":"integer","minimum":0,"maximum":1000000},"daily_limit_cents":{"type":"integer","minimum":0,"maximum":1000000}},"required":["agent_id","claim_token","scopes","max_job_cents","daily_limit_cents"],"additionalProperties":false,"description":"max_job_cents must not exceed daily_limit_cents. USD cents; zero means no spending allowance. Accepting quotes reserves these limits. Wallet signing requires separate owner authorization."},"Agent":{"type":"object","required":["id","name","status","scopes","credential_expires_at","allowances","wallet_status","job_submission_enabled","next_action"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"enum":["pending_authorization","authorized","revoked"]},"scopes":{"type":"array","items":{"enum":["agent:read","jobs:read","jobs:create"]}},"credential_expires_at":{"type":"string","format":"date-time"},"allowances":{"type":"object","properties":{"currency":{"const":"USD"},"max_job_cents":{"type":"integer"},"daily_limit_cents":{"type":"integer"}}},"wallet_status":{"enum":["not_connected","provisioning","active","revoked"]},"job_submission_enabled":{"type":"boolean"},"next_action":{"type":"object","required":["type"],"properties":{"type":{"enum":["owner_approval_required","wallet_setup_required","access_revoked","ready_for_requests","read_jobs"]},"expires_at":{"type":"string","format":"date-time"},"poll_after_seconds":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}}}}}