{"openapi":"3.1.0","info":{"title":"html.contact API","version":"0.1.0","summary":"Instant form backend for static websites.","description":"html.contact turns plain HTML form posts into email notifications, private submission logs, CSV exports, and authenticated attachment downloads.\n\nThere are two credential types:\n\n- **Public form keys** start with `hc_pub_`. They are safe to place in frontend HTML and are used with `POST /f/{formKey}` or `POST /submit`.\n- **Agency API keys** start with `hc_live_`. They are account-owned, carry immutable Full or Restricted grants, may optionally expire, must stay on trusted systems, and are sent as `Authorization: Bearer hc_live_example_DO_NOT_USE`.\n\nPublic browser forms submit `application/x-www-form-urlencoded` or `multipart/form-data`. Public JSON request bodies are not supported. Every input that should be stored needs a `name` attribute.\n\n`*_REPLACE` values in examples are placeholders. Replace them with values from your account before making requests. In curl examples, set `HC_SERVICE_CREDENTIAL`, `ACCOUNT_ID`, `CLIENT_ID`, `FORM_ID`, `SUBMISSION_ID`, and `ATTACHMENT_ID` variables first.\n\nDomain allowlists use `Origin` and `Referer` as browser-source signals. They help block casual cross-site misuse, but they are not cryptographic proof that a request came from a domain.","contact":{"name":"html.contact","url":"https://html.contact"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://html.contact"}],"externalDocs":{"description":"html.contact docs","url":"https://html.contact/docs"},"tags":[{"name":"Public Forms","description":"Unauthenticated browser form submissions using public `hc_pub_` form keys.","externalDocs":{"description":"HTML form guide","url":"https://html.contact/docs/html-forms/"}},{"name":"Accounts","description":"Safe account identity for account-owned Agency API keys.","externalDocs":{"description":"API guide","url":"https://html.contact/docs/api/"}},{"name":"Clients","description":"Client lifecycle and metadata within an explicit fixed or all-client grant.","externalDocs":{"description":"Agency client guide","url":"https://html.contact/docs/agency-clients/"}},{"name":"Forms","description":"Client-scoped form management without recipient or provider access.","externalDocs":{"description":"Getting started","url":"https://html.contact/docs/getting-started/"}},{"name":"Submissions","description":"Authenticated submission logs, filters, detail views, and CSV exports.","externalDocs":{"description":"API guide","url":"https://html.contact/docs/api/"}},{"name":"Attachments","description":"Authenticated downloads for files uploaded through normal HTML file inputs.","externalDocs":{"description":"Attachments guide","url":"https://html.contact/docs/attachments/"}},{"name":"Usage","description":"Safe submission usage summaries for warning users before they reach submission limits.","externalDocs":{"description":"API guide","url":"https://html.contact/docs/api/"}}],"x-agent-notes":["Never expose hc_live Agency API keys in frontend code, logs, repositories, screenshots, or prompts.","Use hc_pub public form keys only in HTML.","Every input that should be collected needs a name attribute.","Use method=\"POST\" for browser forms.","Public form posts support application/x-www-form-urlencoded and multipart/form-data, not JSON bodies.","Whitelisted domains use Origin/Referer as browser-source signals, not cryptographic proof.","The submitted field named subject is a normal submitted field and controls notification subject when present. _subject and _intro are ordinary submitted fields.","Reserved system fields are _redirect, _replyto, _form_name, _source, _tag, _gotcha, any _hc_hp_* honeypot field, cf-turnstile-response, and form_key.","Unsupported routing-looking fields such as _to, _cc, _bcc, and _from are preserved as ordinary submitted fields and never control email routing."],"components":{"securitySchemes":{"agencyServiceCredential":{"type":"http","scheme":"bearer","bearerFormat":"hc_live","description":"Account-owned Agency API key with an immutable Full or Restricted grant and optional expiration. Keep `hc_live_` keys on trusted servers, automations, or approved agents only."}},"responses":{"RateLimited":{"description":"Too many requests were sent in the current rate-limit window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimited":{"summary":"Rate limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many submissions. Please try again shortly."}}}}}}}},"schemas":{"ErrorBody":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","examples":["domain_not_allowed"]},"message":{"type":"string","description":"Human-readable error message.","examples":["This form is not allowed on this website."]}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"$ref":"#/components/schemas/ErrorBody"}},"examples":[{"ok":false,"error":{"code":"domain_not_allowed","message":"This form is not allowed on this website."}}]},"PublicFormSubmission":{"type":"object","description":"A normal browser form payload. Any named non-reserved field is stored. Duplicate names are stored as arrays.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"properties":{"name":{"type":"string","example":"Mara Quill"},"email":{"type":"string","format":"email","example":"mara@example.com"},"phone":{"type":"string","example":"+1 317 555 0198"},"company":{"type":"string","example":"Tiny Bakery"},"subject":{"type":"string","description":"Normal submitted field that also controls the notification email subject when present.","example":"Quote request"},"message":{"type":"string","example":"Can you send pricing for a five page site?"},"_redirect":{"type":"string","format":"uri","description":"Reserved system field. Optional redirect URL considered after successful browser submission before the form default redirect. Use an absolute https:// URL, or localhost/127.0.0.1 http URL for local development.","example":"https://example.com/thanks"},"_replyto":{"type":"string","description":"Reserved system field. Email address or field name used to infer reply-to. Example: `email` points to the submitted email field.","example":"email"},"_form_name":{"type":"string","description":"Reserved metadata field stored with system fields.","example":"Contact"},"_source":{"type":"string","description":"Reserved metadata field stored with system fields.","example":"homepage"},"_tag":{"type":"string","description":"Reserved metadata field stored with system fields.","example":"quote"},"_gotcha":{"type":"string","description":"Reserved system honeypot field. Leave empty in real browser forms.","example":""},"_hc_hp_extra":{"type":"string","description":"Example autofill-resistant `_hc_hp_*` honeypot system field. Any field name beginning with `_hc_hp_` is stored with system fields and rejected if filled. Use neutral names such as `_hc_hp_extra`; avoid profile-shaped names such as `_hc_hp_company`, `_hc_hp_name`, `_hc_hp_email`, `_hc_hp_phone`, `_hc_hp_website`, or `_hc_hp_address`.","example":""},"cf-turnstile-response":{"type":"string","description":"Reserved system field for customer-managed challenge data. Default html.contact snippets do not require it."}},"examples":[{"name":"Mara Quill","email":"mara@example.com","subject":"Quote request","message":"Can you send pricing for a five page site?"}]},"PublicFormSubmissionMultipart":{"allOf":[{"$ref":"#/components/schemas/PublicFormSubmission"}],"type":"object","properties":{"attachment":{"type":"string","format":"binary","description":"One non-empty file input. Current limit is one attachment up to 4 MB."}}},"PublicFormSubmissionWithHiddenKey":{"allOf":[{"$ref":"#/components/schemas/PublicFormSubmission"}],"type":"object","required":["form_key"],"properties":{"form_key":{"type":"string","pattern":"^hc_pub_[A-Za-z0-9]{36}$","description":"Public form key used by the compatibility `/submit` endpoint.","example":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ"}}},"PublicFormSubmissionWithHiddenKeyMultipart":{"allOf":[{"$ref":"#/components/schemas/PublicFormSubmissionWithHiddenKey"}],"type":"object","required":["form_key"],"properties":{"attachment":{"type":"string","format":"binary","description":"One non-empty file input. Current limit is one attachment up to 4 MB."}}},"SubmissionAccepted":{"type":"object","required":["ok","submission_id","email_status"],"properties":{"ok":{"type":"boolean","const":true},"submission_id":{"type":"string","example":"sub_REPLACE"},"email_status":{"type":"string","enum":["not_attempted","pending","provider_accepted","queued","delivered","failed","bounced","suppressed","unknown"],"example":"provider_accepted"}}},"RateLimit":{"type":"object","description":"Public submit rate-limit policy information. The current error body returns only `rate_limited` and a message.","properties":{"code":{"type":"string","example":"rate_limited"},"window_seconds":{"type":"integer","example":60},"max_requests":{"type":"integer","example":5}}},"AgencyError":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"EmptyObject":{"type":"object","additionalProperties":false,"maxProperties":0},"AgencyAccount":{"type":"object","additionalProperties":false,"required":["id","status","createdAt","revision"],"properties":{"id":{"type":"string"},"status":{"type":"string","const":"active"},"createdAt":{"type":"string","format":"date-time"},"revision":{"type":"integer","minimum":1}}},"AgencyClient":{"type":"object","additionalProperties":false,"required":["id","name","kind","status","createdAt","revision"],"properties":{"id":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","enum":["default","client"]},"status":{"type":"string","enum":["active","archived"]},"createdAt":{"type":"string","format":"date-time"},"revision":{"type":"integer","minimum":1}}},"AgencyClientWrite":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80}}},"AgencyAccountUsage":{"type":"object","additionalProperties":false,"required":["periodKey","periodStart","periodEnd","used","limit","remaining","canAcceptSubmissions"],"properties":{"periodKey":{"type":"string"},"periodStart":{"type":["string","null"],"format":"date-time"},"periodEnd":{"type":["string","null"],"format":"date-time"},"used":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"canAcceptSubmissions":{"type":"boolean"}}},"AgencyClientUsage":{"type":"object","additionalProperties":false,"required":["clientId","periodKey","periodStart","periodEnd","acceptedSubmissions"],"properties":{"clientId":{"type":"string"},"periodKey":{"type":"string"},"periodStart":{"type":["string","null"],"format":"date-time"},"periodEnd":{"type":["string","null"],"format":"date-time"},"acceptedSubmissions":{"type":"integer","minimum":0}}},"AgencyForm":{"type":"object","additionalProperties":false,"required":["id","publicKey","name","status","allowedDomains","emailNotificationsEnabled","allowDirectPosts","defaultRedirectUrl","honeypotField","createdAt","updatedAt","snippet"],"properties":{"id":{"type":"string"},"publicKey":{"type":"string","pattern":"^hc_pub_[A-Za-z0-9]{36}$"},"name":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"allowedDomains":{"type":"array","maxItems":50,"items":{"type":"string"}},"emailNotificationsEnabled":{"type":"boolean"},"allowDirectPosts":{"type":"boolean"},"defaultRedirectUrl":{"type":["string","null"]},"honeypotField":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"snippet":{"type":"string"}}},"AgencyFormCreate":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120}}},"AgencyFormUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"allowedDomains":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string"}},"emailNotificationsEnabled":{"type":"boolean"},"allowDirectPosts":{"type":"boolean"},"defaultRedirectUrl":{"type":["string","null"]}}},"AgencySubmissionSummary":{"type":"object","additionalProperties":false,"required":["id","formId","formName","status","spamResult","deliveryStatus","archivedAt","attachmentCount","createdAt"],"properties":{"id":{"type":"string"},"formId":{"type":"string"},"formName":{"type":"string","maxLength":120},"status":{"type":"string","enum":["received","accepted","blocked","stored","email_attempted","complete"]},"spamResult":{"type":"string","enum":["not_checked","passed","blocked","suspicious"]},"deliveryStatus":{"type":"string"},"archivedAt":{"type":["string","null"],"format":"date-time"},"attachmentCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}}},"AgencySubmittedField":{"type":"object","additionalProperties":false,"required":["name","values"],"properties":{"name":{"type":"string","maxLength":100},"values":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":4000}}}},"AgencySubmissionAttachment":{"type":"object","additionalProperties":false,"required":["id","fieldName","filename","contentType","byteSize","scanStatus","createdAt"],"properties":{"id":{"type":"string"},"fieldName":{"type":"string","maxLength":100},"filename":{"type":"string","maxLength":255},"contentType":{"type":"string","maxLength":255},"byteSize":{"type":"integer","minimum":0},"scanStatus":{"type":"string","enum":["not_scanned","clean","suspicious","blocked"]},"createdAt":{"type":"string","format":"date-time"}}},"AgencySubmissionDetail":{"allOf":[{"$ref":"#/components/schemas/AgencySubmissionSummary"},{"type":"object","required":["sourceHost","submittedFields","contentTruncated","attachments","attachmentsTruncated"],"properties":{"sourceHost":{"type":["string","null"],"maxLength":253},"submittedFields":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/AgencySubmittedField"}},"contentTruncated":{"type":"boolean"},"attachments":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/AgencySubmissionAttachment"}},"attachmentsTruncated":{"type":"boolean"}}}],"unevaluatedProperties":false}}},"paths":{"/f/{formKey}":{"post":{"tags":["Public Forms"],"operationId":"submitPublicForm","summary":"Submit a public form","description":"Accepts a normal browser form post for a public `hc_pub_` form key.\n\nUse this route as the `action` on a plain HTML form. JSON request bodies are rejected. To receive JSON responses while testing, send `Accept: application/json` or append `?format=json`.","externalDocs":{"description":"HTML form guide","url":"https://html.contact/docs/html-forms/"},"parameters":[{"name":"formKey","in":"path","required":true,"schema":{"type":"string","pattern":"^hc_pub_[A-Za-z0-9]{36}$"},"example":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","description":"Public form key safe for frontend HTML."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Use `json` to request JSON responses from a browser-style form submission."}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublicFormSubmission"},"examples":{"basicContact":{"summary":"Basic contact form","value":{"name":"Mara Quill","email":"mara@example.com","message":"Can you send pricing for a five page site?"}},"withPhoneCompany":{"summary":"Contact form with phone and company","value":{"name":"Kaine Hudson","email":"kaine@example.com","phone":"+1 317 555 0198","company":"Hudson Studio","message":"We need a working contact form on a static launch page."}},"systemFields":{"summary":"Reserved system fields","value":{"name":"Mara Quill","email":"mara@example.com","subject":"Quote request","_replyto":"email","_redirect":"https://example.com/thanks","_hc_hp_extra":"","message":"Please send the estimate to my inbox."}}}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicFormSubmissionMultipart"},"encoding":{"attachment":{"contentType":"application/pdf,image/png,image/jpeg,text/plain"}},"examples":{"withFileUpload":{"summary":"Contact form with one attachment","value":{"name":"Mara Quill","email":"mara@example.com","subject":"Quote request","message":"The project brief is attached.","attachment":"quote-request.pdf"}}}}}},"responses":{"200":{"description":"Submission accepted. JSON is returned when the request asks for JSON with `Accept: application/json` or `?format=json`; normal browser posts receive a small HTML success page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionAccepted"},"examples":{"accepted":{"summary":"Submission accepted","value":{"ok":true,"submission_id":"sub_REPLACE","email_status":"provider_accepted"}},"acceptedNoEmail":{"summary":"Stored without email delivery","value":{"ok":true,"submission_id":"sub_01JZ8M7M7FE7CX6N9V2Q8R3D4A","email_status":"not_attempted"}}}},"text/html":{"schema":{"type":"string"},"examples":{"browserSuccess":{"summary":"Browser success page","value":"<!doctype html><html><body><main><h1>Your form was received</h1><p>Thanks. The submission was accepted and saved, so the site owner can review it.</p></main></body></html>"}}}}},"303":{"description":"Redirect after a successful browser form post. Submitted `_redirect` is considered first; otherwise the form default redirect URL is considered. Redirect URLs must be absolute https:// URLs, except localhost and 127.0.0.1 http URLs for local development. If the chosen URL is missing or invalid, the normal success response is returned.","headers":{"Location":{"description":"Destination URL for the visitor.","schema":{"type":"string","format":"uri"}}}},"400":{"description":"The form payload was invalid, tripped the honeypot, exceeded field/file limits, or was rejected by spam screening.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validationError":{"summary":"Validation error","value":{"ok":false,"error":{"code":"validation_error","message":"The form submission could not be parsed."}}},"honeypotTriggered":{"summary":"Honeypot filled","value":{"ok":false,"error":{"code":"honeypot_triggered","message":"The form could not be submitted."}}},"spamRejected":{"summary":"Spam rejected","value":{"ok":false,"error":{"code":"spam_detected","message":"This message could not be submitted."}}},"tooManyFields":{"summary":"Too many fields","value":{"ok":false,"error":{"code":"too_many_fields","message":"The form has too many fields."}}},"tooManyFiles":{"summary":"Too many files","value":{"ok":false,"error":{"code":"too_many_files","message":"Only one attachment is supported per submission."}}},"fileTooLarge":{"summary":"File too large","value":{"ok":false,"error":{"code":"file_too_large","message":"Attachments must be 4 MB or smaller."}}},"payloadTooLarge":{"summary":"Payload too large","value":{"ok":false,"error":{"code":"payload_too_large","message":"The submitted form is too large."}}}}}}},"402":{"description":"The account reached its submission usage limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"usageLimitReached":{"summary":"Usage limit reached","value":{"ok":false,"error":{"code":"usage_limit_reached","message":"This account has reached its submission usage limit."}}}}}}},"403":{"description":"The form is inactive or the source is missing/not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"originMissing":{"summary":"Missing source headers","value":{"ok":false,"error":{"code":"origin_missing","message":"This form must be submitted from an allowed website."}}},"domainNotAllowed":{"summary":"Domain not allowed","value":{"ok":false,"error":{"code":"domain_not_allowed","message":"This form is not allowed on this website."}}},"formInactive":{"summary":"Form inactive","value":{"ok":false,"error":{"code":"form_inactive","message":"This form is not accepting submissions."}}}}}}},"404":{"description":"The public form key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingFormKey":{"summary":"Missing form key","value":{"ok":false,"error":{"code":"form_not_found","message":"Missing form key."}}},"invalidFormKey":{"summary":"Invalid public form key","value":{"ok":false,"error":{"code":"form_not_found","message":"This form was not found."}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The submission or its attachment could not be stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"attachmentStoreFailed":{"summary":"Attachment store failed","value":{"ok":false,"error":{"code":"attachment_store_failed","message":"The attachment could not be stored. Please try again."}}},"storageFailed":{"summary":"Submission storage failed","value":{"ok":false,"error":{"code":"storage_failed","message":"The submission could not be stored. Please try again."}}}}}}},"503":{"description":"Submission storage is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storageTemporarilyUnavailable":{"summary":"Submission storage temporarily unavailable","value":{"ok":false,"error":{"code":"storage_failed","message":"The submission service is temporarily unavailable. Please try again shortly."}}}}}}}}}},"/submit":{"post":{"tags":["Public Forms"],"operationId":"submitPublicFormWithHiddenKey","summary":"Submit a public form with hidden form key","description":"Compatibility endpoint for forms that include a hidden `form_key` field instead of putting the public key in the URL.","externalDocs":{"description":"HTML form guide","url":"https://html.contact/docs/html-forms/"},"parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Use `json` to request JSON responses from a browser-style form submission."}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublicFormSubmissionWithHiddenKey"},"examples":{"basicContact":{"summary":"Basic contact form","value":{"form_key":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Mara Quill","email":"mara@example.com","message":"Can you send pricing for a five page site?"}},"withPhoneCompany":{"summary":"Contact form with phone and company","value":{"form_key":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Kaine Hudson","email":"kaine@example.com","phone":"+1 317 555 0198","company":"Hudson Studio","message":"We need a working contact form on a static launch page."}},"systemFields":{"summary":"Reserved system fields","value":{"form_key":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Mara Quill","email":"mara@example.com","subject":"Quote request","_replyto":"email","_redirect":"https://example.com/thanks","_hc_hp_extra":"","message":"Please send the estimate to my inbox."}}}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicFormSubmissionWithHiddenKeyMultipart"},"encoding":{"attachment":{"contentType":"application/pdf,image/png,image/jpeg,text/plain"}},"examples":{"withFileUpload":{"summary":"Contact form with one attachment","value":{"form_key":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Mara Quill","email":"mara@example.com","subject":"Quote request","message":"The project brief is attached.","attachment":"quote-request.pdf"}}}}}},"responses":{"200":{"description":"Submission accepted. JSON is returned when the request asks for JSON with `Accept: application/json` or `?format=json`; normal browser posts receive a small HTML success page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionAccepted"},"examples":{"accepted":{"summary":"Submission accepted","value":{"ok":true,"submission_id":"sub_REPLACE","email_status":"provider_accepted"}},"acceptedNoEmail":{"summary":"Stored without email delivery","value":{"ok":true,"submission_id":"sub_01JZ8M7M7FE7CX6N9V2Q8R3D4A","email_status":"not_attempted"}}}},"text/html":{"schema":{"type":"string"},"examples":{"browserSuccess":{"summary":"Browser success page","value":"<!doctype html><html><body><main><h1>Your form was received</h1><p>Thanks. The submission was accepted and saved, so the site owner can review it.</p></main></body></html>"}}}}},"303":{"description":"Redirect after a successful browser form post. Submitted `_redirect` is considered first; otherwise the form default redirect URL is considered. Redirect URLs must be absolute https:// URLs, except localhost and 127.0.0.1 http URLs for local development. If the chosen URL is missing or invalid, the normal success response is returned.","headers":{"Location":{"description":"Destination URL for the visitor.","schema":{"type":"string","format":"uri"}}}},"400":{"description":"The form payload was invalid, tripped the honeypot, exceeded field/file limits, or was rejected by spam screening.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validationError":{"summary":"Validation error","value":{"ok":false,"error":{"code":"validation_error","message":"The form submission could not be parsed."}}},"honeypotTriggered":{"summary":"Honeypot filled","value":{"ok":false,"error":{"code":"honeypot_triggered","message":"The form could not be submitted."}}},"spamRejected":{"summary":"Spam rejected","value":{"ok":false,"error":{"code":"spam_detected","message":"This message could not be submitted."}}},"tooManyFields":{"summary":"Too many fields","value":{"ok":false,"error":{"code":"too_many_fields","message":"The form has too many fields."}}},"tooManyFiles":{"summary":"Too many files","value":{"ok":false,"error":{"code":"too_many_files","message":"Only one attachment is supported per submission."}}},"fileTooLarge":{"summary":"File too large","value":{"ok":false,"error":{"code":"file_too_large","message":"Attachments must be 4 MB or smaller."}}},"payloadTooLarge":{"summary":"Payload too large","value":{"ok":false,"error":{"code":"payload_too_large","message":"The submitted form is too large."}}}}}}},"402":{"description":"The account reached its submission usage limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"usageLimitReached":{"summary":"Usage limit reached","value":{"ok":false,"error":{"code":"usage_limit_reached","message":"This account has reached its submission usage limit."}}}}}}},"403":{"description":"The form is inactive or the source is missing/not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"originMissing":{"summary":"Missing source headers","value":{"ok":false,"error":{"code":"origin_missing","message":"This form must be submitted from an allowed website."}}},"domainNotAllowed":{"summary":"Domain not allowed","value":{"ok":false,"error":{"code":"domain_not_allowed","message":"This form is not allowed on this website."}}},"formInactive":{"summary":"Form inactive","value":{"ok":false,"error":{"code":"form_inactive","message":"This form is not accepting submissions."}}}}}}},"404":{"description":"The public form key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingFormKey":{"summary":"Missing form key","value":{"ok":false,"error":{"code":"form_not_found","message":"Missing form key."}}},"invalidFormKey":{"summary":"Invalid public form key","value":{"ok":false,"error":{"code":"form_not_found","message":"This form was not found."}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The submission or its attachment could not be stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"attachmentStoreFailed":{"summary":"Attachment store failed","value":{"ok":false,"error":{"code":"attachment_store_failed","message":"The attachment could not be stored. Please try again."}}},"storageFailed":{"summary":"Submission storage failed","value":{"ok":false,"error":{"code":"storage_failed","message":"The submission could not be stored. Please try again."}}}}}}},"503":{"description":"Submission storage is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storageTemporarilyUnavailable":{"summary":"Submission storage temporarily unavailable","value":{"ok":false,"error":{"code":"storage_failed","message":"The submission service is temporarily unavailable. Please try again shortly."}}}}}}}}}},"/api/v1/accounts/{accountId}":{"get":{"tags":["Accounts"],"operationId":"getAgencyAccount","summary":"Read account identity","description":"Returns safe identity and revision metadata for the credential's exact Agency account.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["account:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."}],"responses":{"200":{"description":"Safe account identity.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyAccount"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"acct_REPLACE","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":1}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/usage":{"get":{"tags":["Usage"],"operationId":"getAgencyAccountUsage","summary":"Read account usage","description":"Returns account-wide submission allowance only to an all-client credential.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["account:usage:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."}],"responses":{"200":{"description":"Safe account usage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyAccountUsage"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"periodKey":"2026-09","periodStart":"2026-09-01T00:00:00.000Z","periodEnd":"2026-10-01T00:00:00.000Z","used":12,"limit":1000,"remaining":988,"canAcceptSubmissions":true}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients":{"get":{"tags":["Clients"],"operationId":"listAgencyClients","summary":"List visible clients","description":"Lists only clients inside the credential's immutable fixed or all-client grant.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["clients:list"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512},"description":"Opaque signed client cursor from the preceding response. It is bound to the credential and account."}],"responses":{"200":{"description":"Bounded page.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":false,"required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyClient"}},"nextCursor":{"type":["string","null"]}}}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"items":[{"id":"client_REPLACE","name":"Acme","kind":"client","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":1}],"nextCursor":null}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}},"post":{"tags":["Clients"],"operationId":"createAgencyClient","summary":"Create client","description":"Creates an empty client. Only an explicit all-present-and-future client policy may create clients.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["clients:create"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientWrite"},"examples":{"request":{"summary":"Request","value":{"name":"Acme"}}}}}},"responses":{"201":{"description":"Created client.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClient"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"client_REPLACE","name":"Acme","kind":"client","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":1}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}":{"get":{"tags":["Clients"],"operationId":"getAgencyClient","summary":"Read client","description":"Returns one safe client projection when the exact client is visible to the credential.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["client:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."}],"responses":{"200":{"description":"Safe client.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClient"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"client_REPLACE","name":"Acme","kind":"client","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":1}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}},"patch":{"tags":["Clients"],"operationId":"updateAgencyClient","summary":"Rename client","description":"Renames one active visible client using its numeric revision. Restore an archived client before renaming it.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["client:update"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientWrite"},"examples":{"request":{"summary":"Request","value":{"name":"Acme Studio"}}}}}},"responses":{"200":{"description":"Updated client.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClient"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"client_REPLACE","name":"Acme Studio","kind":"client","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":2}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/archive":{"post":{"tags":["Clients"],"operationId":"archiveAgencyClient","summary":"Archive client","description":"Reversibly archives a client, pauses active forms, and prevents new client operations.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["client:archive"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"},"examples":{"request":{"summary":"Request","value":{}}}}}},"responses":{"200":{"description":"Archived client.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClient"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"client_REPLACE","name":"Acme","kind":"client","status":"archived","createdAt":"2026-09-12T12:00:00.000Z","revision":2}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/restore":{"post":{"tags":["Clients"],"operationId":"restoreAgencyClient","summary":"Restore client","description":"Restores an archived client. Its forms remain paused until explicitly activated.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["client:archive"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"},"examples":{"request":{"summary":"Request","value":{}}}}}},"responses":{"200":{"description":"Restored client.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClient"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"client_REPLACE","name":"Acme","kind":"client","status":"active","createdAt":"2026-09-12T12:00:00.000Z","revision":3}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/usage":{"get":{"tags":["Usage"],"operationId":"getAgencyClientUsage","summary":"Read client usage","description":"Returns accepted-submission usage for this client without revealing account-wide capacity.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["client:usage:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."}],"responses":{"200":{"description":"Safe client usage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyClientUsage"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"clientId":"client_REPLACE","periodKey":"2026-09","periodStart":"2026-09-01T00:00:00.000Z","periodEnd":"2026-10-01T00:00:00.000Z","acceptedSubmissions":12}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/forms":{"get":{"tags":["Forms"],"operationId":"listAgencyForms","summary":"List forms","description":"Lists safe form configurations without recipient identity.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":1024},"description":"Opaque signed cursor from the preceding response. It is bound to the credential, tenant, and applicable filters."}],"responses":{"200":{"description":"Bounded page.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":false,"required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyForm"}},"nextCursor":{"type":["string","null"]}}}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"items":[{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Website contact","status":"draft","allowedDomains":[],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}],"nextCursor":null}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}},"post":{"tags":["Forms"],"operationId":"createAgencyForm","summary":"Create draft form","description":"Creates a recipient-free draft with email notifications disabled.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:create"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyFormCreate"},"examples":{"request":{"summary":"Request","value":{"name":"Website contact"}}}}}},"responses":{"201":{"description":"Created form.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyForm"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Website contact","status":"draft","allowedDomains":[],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/forms/{formId}":{"get":{"tags":["Forms"],"operationId":"getAgencyForm","summary":"Read form","description":"Returns one safe form configuration and a credential-bound signed revision.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"formId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"form_REPLACE","description":"Exact form identifier for this account-scoped request."}],"responses":{"200":{"description":"Safe form.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyForm"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Website contact","status":"draft","allowedDomains":[],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}},"patch":{"tags":["Forms"],"operationId":"updateAgencyForm","summary":"Update form settings","description":"Updates a bounded non-routing settings subset. Recipient management is not part of this contract.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:update"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"formId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"form_REPLACE","description":"Exact form identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyFormUpdate"},"examples":{"request":{"summary":"Request","value":{"name":"Main contact","allowedDomains":["example.com"],"allowDirectPosts":false}}}}}},"responses":{"200":{"description":"Updated form.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyForm"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Main contact","status":"draft","allowedDomains":["example.com"],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"body_too_large","value":{"ok":false,"error":{"code":"body_too_large","message":"The request body is too large.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/forms/{formId}/activate":{"post":{"tags":["Forms"],"operationId":"activateAgencyForm","summary":"Activate form","description":"Activate form. The mutation is idempotent and requires the current signed form revision.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:update","forms:activate"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"formId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"form_REPLACE","description":"Exact form identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"responses":{"200":{"description":"Updated form.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyForm"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Website contact","status":"active","allowedDomains":[],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/forms/{formId}/pause":{"post":{"tags":["Forms"],"operationId":"pauseAgencyForm","summary":"Pause form","description":"Pause form. The mutation is idempotent and requires the current signed form revision.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["forms:update","forms:activate"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"formId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"form_REPLACE","description":"Exact form identifier for this account-scoped request."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Caller-generated key retained for 24 hours and bound to the exact credential, operation, resource, and request."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted ETag from the latest resource response."}],"responses":{"200":{"description":"Updated form.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencyForm"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"form_REPLACE","publicKey":"hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ","name":"Website contact","status":"paused","allowedDomains":[],"emailNotificationsEnabled":false,"allowDirectPosts":false,"defaultRedirectUrl":null,"honeypotField":"_gotcha","createdAt":"2026-09-12T12:00:00.000Z","updatedAt":"2026-09-12T12:00:00.000Z","snippet":"<form action=\"https://html.contact/f/hc_pub_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ\" method=\"POST\">...</form>"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}},"ETag":{"description":"Quoted current resource revision.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"True when this response recovered a prior completed mutation.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"409":{"description":"This idempotency key was already used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"conflict":{"summary":"idempotency_conflict","value":{"ok":false,"error":{"code":"idempotency_conflict","message":"This idempotency key was already used for a different request.","requestId":"req_REPLACE"}}},"inProgress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"This request is still in progress. Retry it shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"412":{"description":"The resource changed. Read it again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_failed","value":{"ok":false,"error":{"code":"precondition_failed","message":"The resource changed. Read it again before retrying.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"428":{"description":"An If-Match header from the latest response is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"precondition_required","value":{"ok":false,"error":{"code":"precondition_required","message":"An If-Match header from the latest response is required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/submissions":{"get":{"tags":["Submissions"],"operationId":"listAgencyClientSubmissions","summary":"List client submissions","description":"Returns content-free metadata for submissions in one client.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["submissions:list"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":1024},"description":"Opaque signed cursor from the preceding response. It is bound to the credential, tenant, and applicable filters."},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["received","accepted","blocked","stored","email_attempted","complete"]}},{"name":"spamResult","in":"query","required":false,"schema":{"type":"string","enum":["not_checked","passed","blocked","suspicious"]}}],"responses":{"200":{"description":"Bounded page.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":false,"required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencySubmissionSummary"}},"nextCursor":{"type":["string","null"]}}}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"items":[{"id":"sub_REPLACE","formId":"form_REPLACE","formName":"Website contact","status":"complete","spamResult":"passed","deliveryStatus":"delivered","archivedAt":null,"attachmentCount":1,"createdAt":"2026-09-12T12:30:00.000Z"}],"nextCursor":null}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/forms/{formId}/submissions":{"get":{"tags":["Submissions"],"operationId":"listAgencyFormSubmissions","summary":"List form submissions","description":"Returns the same content-free metadata restricted to one form.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["submissions:list"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"formId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"form_REPLACE","description":"Exact form identifier for this account-scoped request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":1024},"description":"Opaque signed cursor from the preceding response. It is bound to the credential, tenant, and applicable filters."},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["received","accepted","blocked","stored","email_attempted","complete"]}},{"name":"spamResult","in":"query","required":false,"schema":{"type":"string","enum":["not_checked","passed","blocked","suspicious"]}}],"responses":{"200":{"description":"Bounded page.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":false,"required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencySubmissionSummary"}},"nextCursor":{"type":["string","null"]}}}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"items":[{"id":"sub_REPLACE","formId":"form_REPLACE","formName":"Website contact","status":"complete","spamResult":"passed","deliveryStatus":"delivered","archivedAt":null,"attachmentCount":1,"createdAt":"2026-09-12T12:30:00.000Z"}],"nextCursor":null}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/submissions/{submissionId}":{"get":{"tags":["Submissions"],"operationId":"getAgencySubmission","summary":"Read submission detail","description":"Returns bounded untrusted visitor fields and safe attachment metadata. Raw network and internal security fields are omitted.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["submissions:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"sub_REPLACE","description":"Exact submission identifier for this account-scoped request."}],"responses":{"200":{"description":"Bounded submission detail.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AgencySubmissionDetail"}}},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"sub_REPLACE","formId":"form_REPLACE","formName":"Website contact","status":"complete","spamResult":"passed","deliveryStatus":"delivered","archivedAt":null,"attachmentCount":1,"createdAt":"2026-09-12T12:30:00.000Z","sourceHost":"example.com","submittedFields":[{"name":"email","values":["visitor@example.com"]},{"name":"message","values":["Hello"]}],"contentTruncated":false,"attachments":[{"id":"att_REPLACE","fieldName":"attachment","filename":"brief.pdf","contentType":"application/pdf","byteSize":188416,"scanStatus":"clean","createdAt":"2026-09-12T12:30:00.000Z"}],"attachmentsTruncated":false}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/submissions.csv":{"get":{"tags":["Submissions"],"operationId":"exportAgencySubmissionsCsv","summary":"Export submissions CSV","description":"Exports at most 5,000 matching rows with spreadsheet-formula neutralization and authenticated attachment links.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["exports:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"folder","in":"query","required":false,"schema":{"type":"string","enum":["inbox","spam","archived"],"default":"inbox"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"emailStatus","in":"query","required":false,"schema":{"type":"string","maxLength":64}},{"name":"sourceHost","in":"query","required":false,"schema":{"type":"string","maxLength":253}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"formId","in":"query","required":false,"schema":{"type":"string","maxLength":256}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":5000}}],"responses":{"200":{"description":"CSV export.","headers":{"Content-Disposition":{"description":"Generated attachment filename.","schema":{"type":"string"}},"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string"},"examples":{"export":{"summary":"CSV export","value":"Submitted At,Email\\r\\n2026-09-12T12:30:00.000Z,visitor@example.com\\r\\n"}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}},"/api/v1/accounts/{accountId}/clients/{clientId}/submissions/{submissionId}/attachments/{attachmentId}":{"get":{"tags":["Attachments"],"operationId":"downloadAgencyAttachment","summary":"Download submission attachment","description":"Streams one private attachment after a final authority and exact-parent check. Inline is honored only for a safe previewable media type.","security":[{"agencyServiceCredential":[]}],"x-required-capabilities":["attachments:read"],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"acct_REPLACE","description":"Exact account identifier for this account-scoped request."},{"name":"clientId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"client_REPLACE","description":"Exact client identifier for this account-scoped request."},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"sub_REPLACE","description":"Exact submission identifier for this account-scoped request."},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256},"example":"att_REPLACE","description":"Exact attachment identifier for this account-scoped request."},{"name":"disposition","in":"query","required":false,"schema":{"type":"string","enum":["attachment","inline"],"default":"attachment"}}],"responses":{"200":{"description":"Private attachment bytes.","headers":{"Content-Disposition":{"description":"Safe stored filename and effective disposition.","schema":{"type":"string"}},"X-Content-Type-Options":{"schema":{"type":"string","const":"nosniff"}},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"invalid_request","value":{"ok":false,"error":{"code":"invalid_request","message":"The request is invalid.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"unauthorized","value":{"ok":false,"error":{"code":"unauthorized","message":"Authentication required.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"403":{"description":"This credential does not have the required capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"forbidden","value":{"ok":false,"error":{"code":"forbidden","message":"This credential does not have the required capability.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"not_found","value":{"ok":false,"error":{"code":"not_found","message":"The requested resource was not found.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"429":{"description":"Too many Agency API requests. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Too many Agency API requests. Retry shortly.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}},"500":{"description":"Something went wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyError"},"examples":{"error":{"summary":"internal_error","value":{"ok":false,"error":{"code":"internal_error","message":"Something went wrong.","requestId":"req_REPLACE"}}}}}},"headers":{"X-Request-Id":{"description":"Request correlation identifier.","schema":{"type":"string"}}}}}}}}}