{"openapi":"3.1.0","info":{"title":"Reclaim verification letters","version":"1.0.0","description":"Account-free letter creation, $1 PDF purchases, and free PDF verification. Keep task capabilities private."},"servers":[{"url":"https://letters.reclaimprotocol.org"}],"externalDocs":{"url":"https://letters.reclaimprotocol.org/agents.md"},"components":{"securitySchemes":{"taskToken":{"type":"http","scheme":"bearer","description":"Private task token. For PDF upload use uploadToken; for result polling use token."},"machineTaskToken":{"type":"apiKey","in":"header","name":"X-Reclaim-Task-Token","description":"Task token on the MPP purchase endpoint, which reserves Authorization for Payment credentials."}}},"paths":{"/api/v1/letters":{"post":{"operationId":"createLetter","summary":"Prepare a letter and browser sign-in handoff","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":32,"maxLength":128},"description":"Private random retry credential; reuse with identical input only."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["loginUrl","params"],"properties":{"loginUrl":{"type":"string","format":"uri"},"params":{"type":"array","minItems":1,"maxItems":32,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z][A-Za-z0-9]{0,63}$","description":"Start with a letter. No spaces or special characters allowed. Use camelCase like \"fullName\" or \"residentialAddress\"."},"isOptional":{"type":"boolean","default":false}}}},"prompt":{"type":"string","maxLength":10000,"description":"Describe what data to extract and the exact parameter name to store each value under. Use the parameter names exactly as entered. Include any navigation steps."}}}}}},"responses":{"201":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/letters/{letterId}":{"get":{"operationId":"getLetterStatus","summary":"Read progress and confirmed payment status","security":[{"taskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}},"delete":{"operationId":"cancelLetter","summary":"Cancel unfinished verification","security":[{"taskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/letters/{letterId}/checkout":{"post":{"operationId":"createCheckout","summary":"Get the $1 Stripe Checkout URL","security":[{"taskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/letters/{letterId}/purchase":{"post":{"operationId":"machinePurchase","summary":"Pay $1 using MPP; 402 carries WWW-Authenticate payment challenge; retry with Authorization: Payment credential","security":[{"machineTaskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","schema":{"type":"string"},"description":"MPP Payment credential on a payment retry; generated by the payment wallet."}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/letters/{letterId}/download-link":{"post":{"operationId":"getLetterDownload","summary":"Get a private 5-minute download URL after payment","security":[{"taskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/letters/{letterId}/pdf":{"get":{"operationId":"downloadLetter","summary":"Download the paid original PDF","security":[{"taskToken":[]}],"parameters":[{"name":"letterId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Original PDF with embedded evidence.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/pdf-verifications":{"post":{"operationId":"preparePdfVerification","summary":"Prepare a free 15-minute PDF upload task","responses":{"201":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/pdf-verifications/{verificationId}":{"get":{"operationId":"getPdfVerification","summary":"Read verified fields, sources, capture times and issuer status","security":[{"taskToken":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/api/v1/pdf-verifications/{verificationId}/pdf":{"post":{"operationId":"uploadPdf","summary":"Upload the original PDF using the upload-only token","security":[{"taskToken":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Operation result. Follow the returned status and pollAfterSeconds.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}},"requestBody":{"required":true,"content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"Maximum 10 MB"}}}}}},"/api/v1/downloads/{downloadToken}":{"get":{"operationId":"downloadWithGrant","summary":"Redeem a short-lived private download URL","parameters":[{"name":"downloadToken","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Original PDF with embedded evidence.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Request failed (400); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"402":{"description":"Request failed (402); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"403":{"description":"Request failed (403); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"404":{"description":"Request failed (404); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"409":{"description":"Request failed (409); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"413":{"description":"Request failed (413); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"422":{"description":"Request failed (422); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"429":{"description":"Request failed (429); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}},"503":{"description":"Request failed (503); see agent instructions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}