{"openapi":"3.1.0","info":{"title":"AI Human 2.0 API","version":"1.2.0"},"paths":{"/api/v1/auth/verify-email":{"post":{"summary":"Verify a human email address with a single-use token","tags":["Identity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":32}},"required":["token"]}}}},"responses":{"200":{"description":"Email verified and account activated"},"410":{"description":"Token invalid, consumed, or expired"}}}},"/api/v1/auth/resend-verification":{"post":{"summary":"Request a fresh email verification link","tags":["Identity"],"responses":{"202":{"description":"Generic accepted response that does not reveal account state"}}}},"/api/v1/contact":{"post":{"summary":"Send a landing-page contact message to operations","tags":["Public"],"responses":{"202":{"description":"Message queued for secure email delivery"},"429":{"description":"Per-source rate limit reached"}}}},"/api/v1/tasks":{"get":{"summary":"List owned tasks","responses":{"200":{"description":"Task list"}}},"post":{"summary":"Create a task draft","responses":{"201":{"description":"Created task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]}}}}}}},"/api/v1/tasks/{taskId}":{"get":{"summary":"Read an owned task","responses":{"200":{"description":"Task"}}},"patch":{"summary":"Update with optimistic concurrency","responses":{"200":{"description":"Updated"},"409":{"description":"Version conflict"}}}},"/api/v1/tasks/{taskId}/funding-intent":{"post":{"summary":"Prepare funding","responses":{"200":{"description":"Awaiting funding"}}}},"/api/v1/tasks/{taskId}/publish":{"post":{"summary":"Publish funded task","responses":{"200":{"description":"Published"},"409":{"description":"Conflict"}}}},"/api/v1/tasks/{taskId}/cancel":{"post":{"summary":"Cancel eligible task","responses":{"200":{"description":"Cancelled"}}}},"/api/v1/tasks/{taskId}/ratings":{"post":{"summary":"Rate the other participant after task completion","responses":{"201":{"description":"Immutable rating and trust event created"},"403":{"description":"Only a human task participant may rate"},"409":{"description":"Task is not rateable or rating already exists"}}}},"/api/v1/users/{userId}/trust":{"get":{"summary":"Read a rebuildable user trust profile","responses":{"200":{"description":"Trust projection"},"404":{"description":"User not found"}}}},"/api/v1/worker/profile":{"get":{"summary":"Read the authenticated worker profile","responses":{"200":{"description":"Worker profile"}}},"put":{"summary":"Create or replace the authenticated worker profile","responses":{"200":{"description":"Worker profile"}}}},"/api/v1/worker/offers":{"get":{"summary":"List offers for the authenticated worker","responses":{"200":{"description":"Offer list"}}}},"/api/v1/offers/{offerId}":{"get":{"summary":"Read an owned offer","responses":{"200":{"description":"Offer"}}}},"/api/v1/offers/{offerId}/accept":{"post":{"summary":"Atomically accept a pending offer","responses":{"200":{"description":"Task assignment"},"409":{"description":"Offer or assignment conflict"},"410":{"description":"Offer expired"}}}},"/api/v1/offers/{offerId}/decline":{"post":{"summary":"Decline a pending offer","responses":{"200":{"description":"Declined offer"}}}},"/api/v1/tasks/{taskId}/matches":{"get":{"summary":"Inspect eligibility, ranking score and reasons","responses":{"200":{"description":"Match candidates"}}}},"/api/v1/tasks/{taskId}/messages":{"get":{"summary":"List messages visible to a task participant","responses":{"200":{"description":"Task conversation"}}},"post":{"summary":"Send a task message and enqueue notifications","responses":{"201":{"description":"Created message"}}}},"/api/v1/tasks/{taskId}/messages/read":{"post":{"summary":"Update the participant read marker","responses":{"200":{"description":"Read marker"}}}},"/api/v1/tasks/{taskId}/start":{"post":{"summary":"Start an assigned task","responses":{"200":{"description":"Started task"}}}},"/api/v1/tasks/{taskId}/evidence/requirements":{"get":{"summary":"List proof requirements","responses":{"200":{"description":"Proof requirements"}}}},"/api/v1/tasks/{taskId}/evidence/upload-intent":{"post":{"summary":"Create a private presigned evidence upload","responses":{"201":{"description":"Upload intent"},"422":{"description":"Invalid MIME or size"}}}},"/api/v1/evidence/{evidenceId}/complete":{"post":{"summary":"Complete upload and enqueue scanning","responses":{"200":{"description":"Scan pending"}}}},"/api/v1/evidence/{evidenceId}/download-url":{"get":{"summary":"Create an authorized short-lived download URL","responses":{"200":{"description":"Download URL"},"409":{"description":"Evidence not clean"}}}},"/api/v1/tasks/{taskId}/evidence/submit":{"post":{"summary":"Submit a complete proof revision","responses":{"200":{"description":"Verification started"},"422":{"description":"Required evidence missing"}}}},"/api/v1/tasks/{taskId}/verification":{"get":{"summary":"Read latest verification result","responses":{"200":{"description":"Verification run"}}}},"/api/v1/admin/verifications/{runId}/review":{"post":{"summary":"Record an auditable manual override","responses":{"200":{"description":"Review decision"}}}},"/api/v1/tasks/{taskId}/disputes":{"post":{"summary":"Open a dispute during the protected dispute window","responses":{"201":{"description":"Dispute opened and release blocked"},"409":{"description":"Window closed or active dispute exists"}}}},"/api/v1/disputes/{disputeId}":{"get":{"summary":"Read an authorized dispute, evidence, and settlement state","responses":{"200":{"description":"Dispute detail"}}}},"/api/v1/disputes/{disputeId}/evidence":{"post":{"summary":"Attach a clean evidence file or textual statement","responses":{"201":{"description":"Dispute evidence recorded"},"422":{"description":"Evidence is invalid"}}}},"/api/v1/admin/disputes/{disputeId}/decision":{"post":{"summary":"Create one auditable idempotent settlement decision","responses":{"202":{"description":"Settlement command queued"},"409":{"description":"Decision or idempotency conflict"},"422":{"description":"Settlement amounts are invalid"}}}},"/api/v1/admin/dashboard":{"get":{"summary":"Read the audited operational administration dashboard","responses":{"200":{"description":"Operational counts and moderation queue"},"403":{"description":"Administrator access required"}}}},"/api/v1/admin/moderation":{"get":{"summary":"Read the audited moderation queue","responses":{"200":{"description":"Moderation cases"},"403":{"description":"Administrator access required"}}}},"/api/v1/admin/moderation/{caseId}/decision":{"post":{"summary":"Approve, reject, or escalate a moderation case with reason","responses":{"200":{"description":"Audited moderation decision"},"403":{"description":"Administrator access required"},"409":{"description":"Moderation state conflict"}}}},"/api/v1/admin/users/{userId}/status":{"post":{"summary":"Activate or suspend a user with an audited reason","responses":{"200":{"description":"Updated account status"},"403":{"description":"Administrator access required"},"409":{"description":"Unsafe self-administration attempt"}}}},"/api/v1/admin/trust/{userId}/rebuild":{"post":{"summary":"Rebuild a trust projection from immutable source events","responses":{"200":{"description":"Rebuilt trust profile"},"403":{"description":"Administrator access required"},"404":{"description":"User not found"}}}},"/api/v1/me/payment-account":{"get":{"summary":"Read Stripe Connect onboarding status","responses":{"200":{"description":"Connected account status"}}}},"/api/v1/me/payment-account/onboarding-link":{"post":{"summary":"Create a one-time hosted Connect onboarding link","responses":{"201":{"description":"Hosted onboarding link"},"503":{"description":"Payment provider disabled"}}}},"/api/v1/me/earnings":{"get":{"summary":"Read worker payable balances and payout history","responses":{"200":{"description":"Earnings and payouts"}}}},"/api/v1/me/payouts":{"post":{"summary":"Request release for an eligible completed task","responses":{"202":{"description":"Payout submitted or pending confirmation"},"409":{"description":"Release is ineligible or blocked"},"503":{"description":"Payment provider disabled"}}}},"/api/v1/me/payouts/{payoutId}":{"get":{"summary":"Read an owned payout state","responses":{"200":{"description":"Payout state"},"404":{"description":"Payout not found"}}}},"/api/v1/webhooks/stripe":{"post":{"summary":"Ingest a raw signature-verified Stripe event","responses":{"200":{"description":"Accepted or deduplicated event"},"400":{"description":"Invalid signature"}}}},"/api/v1/me/finance":{"get":{"summary":"Read the signed-in user's financial workspace","description":"Returns agent spending limits and usage, task payments, worker payouts, commission invoices, and currency totals.","responses":{"200":{"description":"Financial workspace"}}}},"/api/v1/me/billing-profile":{"get":{"summary":"Read customer billing details","responses":{"200":{"description":"Billing profile or null"}}},"put":{"summary":"Create or update customer billing details","description":"A complete profile lets AI Human 2.0 issue the platform commission invoice automatically after financial allocation.","responses":{"200":{"description":"Saved billing profile"}}}},"/api/v1/me/invoices":{"get":{"summary":"List AI Human 2.0 platform commission invoices","description":"Human sessions see all owned invoices. Agent keys require billing:read and see only invoices for that agent.","responses":{"200":{"description":"Commission invoice list"}}}},"/api/v1/me/invoices/{invoiceId}":{"get":{"summary":"Read a commission invoice","responses":{"200":{"description":"Commission invoice"}}}},"/api/v1/me/invoices/{invoiceId}/pdf":{"get":{"summary":"Download the human-readable PDF invoice","responses":{"200":{"description":"PDF invoice","content":{"application/pdf":{}}}}}},"/api/v1/me/invoices/{invoiceId}/xml":{"get":{"summary":"Download the structured electronic invoice","description":"UBL 2.1 XML aligned with EN 16931.","responses":{"200":{"description":"Electronic invoice","content":{"application/xml":{}}}}}},"/api/v1/admin/billing-settings":{"get":{"summary":"Read commission, issuer, VAT, and numbering settings","responses":{"200":{"description":"Administrator billing settings"}}},"put":{"summary":"Update commission and automatic invoice settings","responses":{"200":{"description":"Saved administrator billing settings"}}}},"/api/v1/admin/invoices/sync":{"post":{"summary":"Discover and issue ready commission invoices","description":"Creates one immutable invoice per financially allocated task and issues it only when issuer and customer billing data are complete.","responses":{"200":{"description":"Invoice synchronization result"},"403":{"description":"Administrator access required"}}}},"/api/v1/admin/invoices/{invoiceId}/pdf":{"get":{"summary":"Download any issued commission invoice as PDF","responses":{"200":{"description":"PDF invoice","content":{"application/pdf":{}}}}}},"/api/v1/admin/invoices/{invoiceId}/xml":{"get":{"summary":"Download any issued commission invoice as UBL XML","responses":{"200":{"description":"UBL 2.1 / EN 16931 electronic invoice","content":{"application/xml":{}}}}}},"/api/v1/me/notification-preferences":{"get":{"summary":"Read notification preferences and critical policy","responses":{"200":{"description":"Preferences"}}},"put":{"summary":"Update ordinary notification preferences","responses":{"200":{"description":"Preferences"}}}},"/api/v1/me/notifications":{"get":{"summary":"List in-app notifications","responses":{"200":{"description":"Notification list"}}}}},"components":{"schemas":{"Task":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"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)$"},"requesterUserId":{"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)$"},"agentId":{"anyOf":[{"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)$"},{"type":"null"}]},"organizationId":{"anyOf":[{"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)$"},{"type":"null"}]},"title":{"type":"string"},"description":{"type":"string"},"categoryId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","AWAITING_FUNDING","OPEN","MATCHING","ASSIGNED","IN_PROGRESS","SUBMITTED","VERIFYING","COMPLETED","CANCELLED","EXPIRED","REJECTED","DISPUTED","REFUND_PENDING","REFUNDED"]},"fundingStatus":{"type":"string","enum":["UNFUNDED","PENDING","FUNDED","FAILED","REFUNDED"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"rewardMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"platformFeeMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"platformFeeRateBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"platformFeePercent":{"type":"number"},"platformFeeNetMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"platformFeeTaxMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"platformFeeTaxTreatment":{"type":"string","enum":["STANDARD","EXEMPT","REVERSE_CHARGE"]},"platformFeeVatRateBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fundingTotalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locationType":{"type":"string","enum":["REMOTE","ONSITE","HYBRID"]},"locationPublic":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"startsAt":{"anyOf":[{"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))$"},{"type":"null"}]},"dueAt":{"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))$"},"expiresAt":{"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))$"},"assigneeUserId":{"anyOf":[{"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)$"},{"type":"null"}]},"riskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","PROHIBITED"]},"policyStatus":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","APPROVED","REJECTED"]},"policyRuleVersion":{"type":"string"},"policyReasonCodes":{"type":"array","items":{"type":"string"}},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"createdAt":{"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))$"},"updatedAt":{"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))$"},"requirements":{"type":"array","items":{}}},"required":["id","requesterUserId","agentId","organizationId","title","description","categoryId","status","fundingStatus","currency","rewardMinor","platformFeeMinor","platformFeeRateBps","platformFeePercent","platformFeeNetMinor","platformFeeTaxMinor","platformFeeTaxTreatment","platformFeeVatRateBps","fundingTotalMinor","locationType","locationPublic","startsAt","dueAt","expiresAt","assigneeUserId","riskLevel","policyStatus","policyRuleVersion","policyReasonCodes","version","createdAt","updatedAt"],"additionalProperties":false}}}}