{"openapi":"3.1.0","info":{"title":"PostalMuse API","version":"1.0.0","description":"Prepare and inspect a proof, then explicitly authorize paid mailing. Sandbox never sends physical mail."},"servers":[{"url":"https://postalmuse.com/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Address":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"company":{"type":"string","maxLength":80},"address_line1":{"type":"string","minLength":1,"maxLength":100},"address_line2":{"type":"string","maxLength":100},"address_city":{"type":"string","minLength":1,"maxLength":80},"address_state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"default":"US","type":"string","const":"US"}},"required":["name","address_line1","address_city","address_state","address_zip","address_country"],"additionalProperties":false},"DraftInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","enum":["postcard","letter"]},"to":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"company":{"type":"string","maxLength":80},"address_line1":{"type":"string","minLength":1,"maxLength":100},"address_line2":{"type":"string","maxLength":100},"address_city":{"type":"string","minLength":1,"maxLength":80},"address_state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"default":"US","type":"string","const":"US"}},"required":["name","address_line1","address_city","address_state","address_zip","address_country"],"additionalProperties":false},"from":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"company":{"type":"string","maxLength":80},"address_line1":{"type":"string","minLength":1,"maxLength":100},"address_line2":{"type":"string","maxLength":100},"address_city":{"type":"string","minLength":1,"maxLength":80},"address_state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"default":"US","type":"string","const":"US"}},"required":["name","address_line1","address_city","address_state","address_zip","address_country"],"additionalProperties":false},"purpose":{"type":"string","enum":["operational","marketing"]},"content":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"template"},"template_id":{"type":"string","enum":["everyday_note","simple_letter","photo_postcard"]},"template_version":{"default":"1","type":"string","const":"1"},"variables":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":40000},"title":{"default":"A note for you","type":"string","maxLength":80},"image_asset_id":{"type":"string"}},"required":["message","title"],"additionalProperties":false}},"required":["type","template_id","template_version","variables"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"asset_id":{"type":"string","minLength":1,"maxLength":80}},"required":["type","asset_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"artwork"},"front_asset_id":{"type":"string","minLength":1,"maxLength":80},"back_asset_id":{"type":"string","minLength":1,"maxLength":80}},"required":["type","front_asset_id","back_asset_id"],"additionalProperties":false}]},"options":{"default":{"color":false,"double_sided":false,"mail_class":"usps_first_class","extra_service":"none","address_placement":"insert_blank_page"},"type":"object","properties":{"color":{"default":false,"type":"boolean"},"double_sided":{"default":false,"type":"boolean"},"mail_class":{"default":"usps_first_class","type":"string","const":"usps_first_class"},"extra_service":{"default":"none","type":"string","enum":["none","certified","certified_return_receipt"]},"address_placement":{"default":"insert_blank_page","type":"string","const":"insert_blank_page"}},"required":["color","double_sided","mail_class","extra_service","address_placement"],"additionalProperties":false},"client_reference":{"type":"string","maxLength":100,"pattern":"^[\\w .:-]*$"}},"required":["kind","to","from","purpose","content","options"],"additionalProperties":false},"Commit":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"draft_revision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"quote_id":{"type":"string","minLength":1,"maxLength":80},"manifest_hash":{"type":"string","minLength":1,"maxLength":80},"max_total_cents":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"USD"}},"required":["draft_revision","quote_id","manifest_hash","max_total_cents","currency"],"additionalProperties":false},"Grant":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":80},"per_mailing_cents":{"type":"integer","minimum":1,"maximum":100000},"daily_cents":{"type":"integer","minimum":1,"maximum":1000000},"lifetime_cents":{"type":"integer","minimum":1,"maximum":10000000},"expires_in_days":{"default":30,"type":"integer","minimum":1,"maximum":90},"products":{"default":["postcard","letter"],"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["postcard","letter"]}},"recipient_names":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}}},"required":["label","per_mailing_cents","daily_cents","lifetime_cents","expires_in_days","products"],"additionalProperties":false},"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"retryable":{"type":"boolean"}}},"request_id":{"type":"string"}}}}},"paths":{"/capabilities":{"get":{"summary":"Discover supported capabilities","operationId":"get__capabilities","security":[],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/pricing":{"get":{"summary":"Discover current or planned retail rates","operationId":"get__pricing","security":[],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/payment-config":{"get":{"summary":"Discover Stripe availability; query mode=sandbox or live","operationId":"get__payment_config","security":[],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/templates":{"get":{"summary":"Discover templates","operationId":"get__templates","security":[],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/sessions":{"post":{"summary":"Create an isolated sandbox or live session","operationId":"post__sessions","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["sandbox","live"]}},"required":["mode"],"additionalProperties":false}}}}}},"/assets":{"post":{"summary":"Upload a private PDF or image","operationId":"post__assets","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}}}},"/assets/{id}":{"get":{"summary":"Get asset preflight and temporary access","operationId":"get__assets_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/addresses/verify":{"post":{"summary":"Verify an address","operationId":"post__addresses_verify","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}}}},"/drafts":{"post":{"summary":"Prepare a mailing; never dispatches","operationId":"post__drafts","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}}}}},"/drafts/{id}":{"get":{"summary":"Get proof, quote, and readiness","operationId":"get__drafts_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}},"patch":{"summary":"Revise an uncommitted draft","operationId":"patch__drafts_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","enum":["postcard","letter"]},"to":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"company":{"type":"string","maxLength":80},"address_line1":{"type":"string","minLength":1,"maxLength":100},"address_line2":{"type":"string","maxLength":100},"address_city":{"type":"string","minLength":1,"maxLength":80},"address_state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"default":"US","type":"string","const":"US"}},"required":["name","address_line1","address_city","address_state","address_zip","address_country"],"additionalProperties":false},"from":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"company":{"type":"string","maxLength":80},"address_line1":{"type":"string","minLength":1,"maxLength":100},"address_line2":{"type":"string","maxLength":100},"address_city":{"type":"string","minLength":1,"maxLength":80},"address_state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"default":"US","type":"string","const":"US"}},"required":["name","address_line1","address_city","address_state","address_zip","address_country"],"additionalProperties":false},"purpose":{"type":"string","enum":["operational","marketing"]},"content":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"template"},"template_id":{"type":"string","enum":["everyday_note","simple_letter","photo_postcard"]},"template_version":{"default":"1","type":"string","const":"1"},"variables":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":40000},"title":{"default":"A note for you","type":"string","maxLength":80},"image_asset_id":{"type":"string"}},"required":["message","title"],"additionalProperties":false}},"required":["type","template_id","template_version","variables"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"asset_id":{"type":"string","minLength":1,"maxLength":80}},"required":["type","asset_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"artwork"},"front_asset_id":{"type":"string","minLength":1,"maxLength":80},"back_asset_id":{"type":"string","minLength":1,"maxLength":80}},"required":["type","front_asset_id","back_asset_id"],"additionalProperties":false}]},"options":{"default":{"color":false,"double_sided":false,"mail_class":"usps_first_class","extra_service":"none","address_placement":"insert_blank_page"},"type":"object","properties":{"color":{"default":false,"type":"boolean"},"double_sided":{"default":false,"type":"boolean"},"mail_class":{"default":"usps_first_class","type":"string","const":"usps_first_class"},"extra_service":{"default":"none","type":"string","enum":["none","certified","certified_return_receipt"]},"address_placement":{"default":"insert_blank_page","type":"string","const":"insert_blank_page"}},"required":["color","double_sided","mail_class","extra_service","address_placement"],"additionalProperties":false},"client_reference":{"type":"string","maxLength":100,"pattern":"^[\\w .:-]*$"},"expected_revision":{"type":"integer","minimum":1}},"required":["kind","to","from","purpose","content","options","expected_revision"],"additionalProperties":false}}}}}},"/drafts/{id}/quote":{"post":{"summary":"Refresh the quote","operationId":"post__drafts_id_quote","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/drafts/{id}/checkout":{"post":{"summary":"Start customer review and purchase","operationId":"post__drafts_id_checkout","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Commit"}}}}}},"/drafts/{id}/send":{"post":{"summary":"Send through sandbox or delegated authority","operationId":"post__drafts_id_send","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Commit"}}}}}},"/checkouts/{id}":{"get":{"summary":"Read the private checkout","operationId":"get__checkouts_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/checkouts/{id}/pay":{"post":{"summary":"Simulate sandbox payment or create Stripe Checkout","operationId":"post__checkouts_id_pay","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["approve"],"properties":{"approve":{"const":true},"processor":{"type":"string","enum":["simulation","stripe"]},"ui_mode":{"type":"string","enum":["hosted","embedded"]}}}}}}}},"/checkouts/{id}/cancel":{"post":{"summary":"Cancel an unpaid checkout","operationId":"post__checkouts_id_cancel","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/mailings":{"get":{"summary":"List recoverable mailing history","operationId":"get__mailings","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/mailings/{id}":{"get":{"summary":"Retrieve independent payment and delivery state","operationId":"get__mailings_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/mailings/{id}/events":{"get":{"summary":"Retrieve the mailing event timeline","operationId":"get__mailings_id_events","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/mailings/{id}/cancel":{"post":{"summary":"Request confirmed cancellation","operationId":"post__mailings_id_cancel","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/account":{"get":{"summary":"Read balance and effective grants","operationId":"get__account","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/auth/start":{"post":{"summary":"Request email verification","operationId":"post__auth_start","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}}}},"/auth/verify":{"post":{"summary":"Verify sign-in code","operationId":"post__auth_verify","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","code"],"properties":{"id":{"type":"string"},"code":{"type":"string","pattern":"^[0-9]{6}$"}}}}}}}},"/funding-sessions":{"post":{"summary":"Create hosted funding or simulated sandbox funds","operationId":"post__funding_sessions","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents"],"properties":{"amount_cents":{"type":"integer","minimum":500,"maximum":50000},"processor":{"type":"string","enum":["simulation","stripe"]}}}}}}}},"/grants":{"post":{"summary":"Customer-authorized spending grant","operationId":"post__grants","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}}}},"/grants/{id}":{"delete":{"summary":"Revoke authority","operationId":"delete__grants_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/account-links":{"post":{"summary":"Request customer approval","operationId":"post__account_links","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}}}},"/account-links/{id}":{"get":{"summary":"Retrieve approval state and one-time token","operationId":"get__account_links_id_","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/account-links/{id}/request":{"get":{"summary":"Customer inspects requested authority","operationId":"get__account_links_id_request","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}}}},"/account-links/{id}/approve":{"post":{"summary":"Customer approves the requested grant","operationId":"post__account_links_id_approve","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Operation result"},"201":{"description":"Created"},"202":{"description":"Accepted; poll returned resource"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required"},"409":{"description":"Revision, price, or idempotency conflict"},"422":{"description":"Correct input"},"429":{"description":"Rate limited; respect Retry-After"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["approve"],"properties":{"approve":{"const":true}}}}}}}}}}