{"openapi":"3.1.0","info":{"description":"Quote, approve, pay for, and track personalized handwritten cards.","title":"SendInkwire API","version":"0.2.0"},"x-service-info":{"categories":["mail","physical","cards"],"docs":{"apiReference":"/openapi.json","homepage":"/","llms":"/llms.txt"}},"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"Opaque read token returned once at creation."},"campaignToken":{"type":"apiKey","in":"header","name":"X-Campaign-Token"},"agentKey":{"type":"http","scheme":"bearer","bearerFormat":"Inkwire agent key"},"agentDelegation":{"type":"apiKey","in":"header","name":"X-Inkwire-Delegation","description":"Customer-owned, scoped, expiring delegation secret."},"clerkSession":{"type":"http","scheme":"bearer","bearerFormat":"Clerk session JWT"},"clerkSessionCookie":{"type":"apiKey","in":"cookie","name":"__session","description":"Read-only Clerk session fallback. Account mutations require clerkSession Bearer auth."}},"schemas":{"Address":{"type":"object","additionalProperties":false,"required":["city","firstName","state","street1","zip"],"properties":{"city":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":100},"firstName":{"type":"string","maxLength":60},"lastName":{"type":"string","maxLength":60},"state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"street1":{"type":"string","maxLength":120},"street2":{"type":"string","maxLength":120},"zip":{"type":"string","pattern":"^\\d{5}$"}}},"CardRequest":{"type":"object","additionalProperties":false,"required":["card","handwriting","message","recipient","sender"],"properties":{"card":{"type":"string","maxLength":100},"handwriting":{"type":"string","maxLength":100},"message":{"type":"string","minLength":1,"maxLength":2000},"recipient":{"$ref":"#/components/schemas/Address"},"sender":{"$ref":"#/components/schemas/Address"}}},"MessageReview":{"type":"object","additionalProperties":false,"required":["findings","normalized","original","policyVersion"],"properties":{"findings":{"type":"array","items":{"type":"object"}},"normalized":{"type":"string"},"original":{"type":"string"},"policyVersion":{"const":"handwrite-ascii-v1"}}},"PublicQuote":{"type":"object","additionalProperties":false,"required":["approvalHash","createdAt","currency","expiresAt","id","messageReview","priceCents","recipient"],"properties":{"approvalHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"createdAt":{"type":"string","format":"date-time"},"currency":{"const":"usd"},"expiresAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"messageReview":{"$ref":"#/components/schemas/MessageReview"},"priceCents":{"type":"integer","minimum":1},"recipient":{"$ref":"#/components/schemas/Address"}}},"PublicCampaignQuoteItem":{"type":"object","additionalProperties":false,"required":["addressValidation","externalId","message","messageReview","recipient"],"properties":{"addressValidation":{"const":"format_valid_unverified"},"externalId":{"type":"string"},"message":{"type":"string"},"messageReview":{"$ref":"#/components/schemas/MessageReview"},"recipient":{"$ref":"#/components/schemas/Address"}}},"PublicCampaignQuote":{"type":"object","additionalProperties":false,"required":["approvalHash","count","createdAt","currency","expiresAt","id","items","priceCents","unitPriceCents"],"properties":{"approvalHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"count":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"currency":{"const":"usd"},"expiresAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicCampaignQuoteItem"}},"priceCents":{"type":"integer","minimum":1},"unitPriceCents":{"type":"integer","minimum":1}}},"PublicCampaign":{"type":"object","additionalProperties":false,"required":["count","counts","createdAt","currency","id","items","paymentMode","priceCents","quoteId","status","unitPriceCents","updatedAt"],"properties":{"canceledAt":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":1},"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"createdAt":{"type":"string","format":"date-time"},"currency":{"const":"usd"},"id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"type":"object"}},"paymentMode":{"type":"string","enum":["mock","stripe","tempo"]},"priceCents":{"type":"integer","minimum":1},"quoteId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","canceled","processing","complete","needs_review"]},"unitPriceCents":{"type":"integer","minimum":1},"updatedAt":{"type":"string","format":"date-time"}}},"CampaignCreation":{"allOf":[{"$ref":"#/components/schemas/PublicCampaign"},{"type":"object","required":["campaignToken","receiptUrl","replayed"],"properties":{"campaignToken":{"type":"string","writeOnly":true},"receiptUrl":{"type":"string","format":"uri"},"replayed":{"type":"boolean"}}}]},"CampaignPreflight":{"type":"object","additionalProperties":false,"required":["campaignId","checks","ready","recipientCount","status"],"properties":{"campaignId":{"type":"string","format":"uuid"},"checks":{"type":"object"},"ready":{"type":"boolean"},"recipientCount":{"type":"integer","minimum":1},"status":{"type":"string","enum":["ready","ready_with_warnings","blocked"]}}},"ApprovedQuote":{"type":"object","additionalProperties":false,"required":["approvedContentHash","quoteId"],"properties":{"approvedContentHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"quoteId":{"type":"string","format":"uuid"}}},"CampaignQuoteRequest":{"type":"object","additionalProperties":false,"required":["card","handwriting","messageTemplate","recipients","sender"],"properties":{"card":{"type":"string","maxLength":100},"handwriting":{"type":"string","maxLength":100},"messageTemplate":{"type":"string","minLength":1,"maxLength":2000},"sender":{"$ref":"#/components/schemas/Address"},"recipients":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["externalId","recipient"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":100},"messageOverride":{"type":"string","minLength":1,"maxLength":2000},"recipient":{"$ref":"#/components/schemas/Address"},"variables":{"type":"object","additionalProperties":{"type":"string","maxLength":500}}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"detail":{"type":"string"},"issues":{"type":"array","items":{}}}},"Customer":{"type":"object","required":["createdAt","id"],"properties":{"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"}}},"AgentDelegation":{"type":"object","required":["agentKeyId","createdAt","expiresAt","id","scopes"],"properties":{"agentKeyId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"revokedAt":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string","enum":["account:read","event:create","event:read","event:update","recipient:write","address-request:send","letter:draft","letter:approve","event:publish","payment:prepare","event:delete"]}},"token":{"type":"string","writeOnly":true,"description":"Returned only when the delegation is created."}}},"Catalog":{"type":"object","required":["handwritings","stationery"],"properties":{"handwritings":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"stationery":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}}},"CatalogItem":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"previewUrl":{"type":"string","format":"uri"}}},"EventRecipientInput":{"type":"object","additionalProperties":false,"required":["externalId","firstName"],"properties":{"email":{"type":"string","format":"email"},"externalId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":60},"lastName":{"type":"string","maxLength":60},"notes":{"type":"string","maxLength":1000},"recipient":{"$ref":"#/components/schemas/Address"}}},"EventCreate":{"type":"object","additionalProperties":false,"required":["card","handwriting","hostName","name","purpose","sender","tone"],"properties":{"card":{"type":"string","maxLength":100},"eventDate":{"type":"string","format":"date"},"handwriting":{"type":"string","maxLength":100},"hostName":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":160},"purpose":{"type":"string","maxLength":1000},"sender":{"$ref":"#/components/schemas/Address"},"sharedContext":{"type":"string","maxLength":4000},"tone":{"type":"string","maxLength":200}}},"Event":{"type":"object","required":["card","contentHash","createdAt","handwriting","hostName","id","name","purpose","readiness","recipients","status","tone","updatedAt","version"],"properties":{"card":{"type":"string"},"campaignDraftId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"contentHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"eventDate":{"type":"string","format":"date"},"handwriting":{"type":"string"},"hostName":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"purpose":{"type":"string"},"readiness":{"type":"object"},"recipients":{"type":"array","items":{"type":"object"}},"sender":{"$ref":"#/components/schemas/Address"},"sharedContext":{"type":"string"},"status":{"type":"string"},"tone":{"type":"string"},"tracking":{"type":"object"},"updatedAt":{"type":"string","format":"date-time"},"version":{"type":"integer","minimum":1}}},"CampaignDraft":{"type":"object","required":["id","input","preview","status","updatedAt","version"],"properties":{"id":{"type":"string","format":"uuid"},"input":{"$ref":"#/components/schemas/CampaignQuoteRequest"},"preview":{"type":"object"},"status":{"type":"string","enum":["editable","checkout_locked","mpp_locked","converted"]},"updatedAt":{"type":"string","format":"date-time"},"version":{"type":"integer","minimum":1}}},"PaymentPreparation":{"oneOf":[{"type":"object","required":["checkoutUrl","expiresAt","method","status","version"],"properties":{"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"method":{"const":"card"},"status":{"const":"checkout_locked"},"version":{"type":"integer"}}},{"type":"object","required":["campaignId","campaignToken","idempotencyKey","instructions","method","receiptUrl","sendUrl","status","version"],"properties":{"campaignId":{"type":"string","format":"uuid"},"campaignToken":{"type":"string"},"idempotencyKey":{"type":"string"},"instructions":{"type":"string"},"method":{"const":"mpp"},"receiptUrl":{"type":"string","format":"uri","description":"Private human receipt link. Its fragment contains a one-time account claim token until claimed."},"sendUrl":{"type":"string","format":"uri"},"status":{"const":"mpp_locked"},"version":{"type":"integer"}}}]},"CustomerActivity":{"type":"object","required":["actorType","capability","createdAt","id","outcome","ownerCustomerId","resourceType"],"properties":{"actorType":{"type":"string","enum":["agent","human"]},"capability":{"type":"string","enum":["account:read","event:create","event:read","event:update","recipient:write","address-request:send","letter:draft","letter:approve","event:publish","payment:prepare","event:delete"]},"createdAt":{"type":"string","format":"date-time"},"delegationId":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"outcome":{"const":"succeeded"},"ownerCustomerId":{"type":"string","format":"uuid"},"resourceId":{"type":"string","format":"uuid"},"resourceType":{"type":"string"}}},"AccountOrderSummary":{"type":"object","required":["createdAt","currency","id","paymentMode","priceCents","quoteId","status"],"properties":{"createdAt":{"type":"string","format":"date-time"},"currency":{"type":"string","const":"usd"},"fulfillmentReference":{"type":"string"},"id":{"type":"string","format":"uuid"},"paymentMode":{"type":"string","enum":["mock","stripe"]},"priceCents":{"type":"integer","minimum":1},"quoteId":{"type":"string","format":"uuid"},"recipient":{"type":"object","required":["city","firstName","state"],"properties":{"city":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"state":{"type":"string"}}},"status":{"type":"string","enum":["processing","written","complete","failed","needs_review"]}}},"AccountOrderDetail":{"allOf":[{"$ref":"#/components/schemas/AccountOrderSummary"},{"type":"object","properties":{"letter":{"type":"object","required":["card","handwriting","message","recipient","sender"],"properties":{"card":{"type":"string"},"handwriting":{"type":"string"},"message":{"type":"string"},"recipient":{"$ref":"#/components/schemas/Address"},"sender":{"$ref":"#/components/schemas/Address"}}},"preview":{"type":"object","required":["fidelity","notice"],"properties":{"fidelity":{"type":"string","const":"illustrative"},"notice":{"type":"string"}}}}}]},"AccountOrderList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AccountOrderSummary"}},"nextCursor":{"type":"string"}}},"FulfillmentProof":{"type":"object","additionalProperties":false,"required":["imageUrl","jobType"],"properties":{"imageUrl":{"type":"string","format":"uri"},"jobType":{"type":"string","maxLength":80}}},"AccountCampaignLetterSummary":{"type":"object","required":["externalId","status"],"properties":{"externalId":{"type":"string"},"recipient":{"type":"object","required":["city","firstName","state"],"properties":{"city":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"state":{"type":"string"}}},"status":{"type":"string","enum":["pending","processing","written","complete","failed","needs_review"]}}},"AccountCampaignSummary":{"type":"object","required":["count","createdAt","id","letters","priceCents","receiptUrl","status","updatedAt"],"properties":{"count":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"letters":{"type":"array","items":{"$ref":"#/components/schemas/AccountCampaignLetterSummary"}},"priceCents":{"type":"integer","minimum":1},"receiptUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["draft","canceled","processing","complete","needs_review"]},"updatedAt":{"type":"string","format":"date-time"}}},"AccountCampaignDetail":{"allOf":[{"$ref":"#/components/schemas/AccountCampaignSummary"},{"type":"object","required":["counts","items","unitPriceCents"],"properties":{"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"items":{"type":"array","items":{"type":"object","required":["externalId","status"],"properties":{"card":{"type":"string"},"externalId":{"type":"string"},"handwriting":{"type":"string"},"message":{"type":"string"},"proofs":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentProof"}},"recipient":{"$ref":"#/components/schemas/Address"},"sender":{"$ref":"#/components/schemas/Address"},"status":{"type":"string","enum":["pending","processing","written","complete","failed","needs_review"]}}}},"unitPriceCents":{"type":"integer","minimum":1}}}]},"AccountCampaignList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AccountCampaignSummary"}},"nextCursor":{"type":"string"}}}}},"paths":{"/v1/catalog":{"get":{"operationId":"getCatalog","responses":{"200":{"description":"Available stationery and handwriting identifiers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/v1/me":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"responses":{"200":{"description":"Current SendInkwire customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Customer accounts are not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/activity":{"get":{"operationId":"listCustomerActivity","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"account:read","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Content-free activity owned by the current customer","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomerActivity"}}}}}}}}}},"/v1/me/events":{"get":{"operationId":"listEvents","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:read","responses":{"200":{"description":"Customer events","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}},"post":{"operationId":"createEvent","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCreate"}}}},"responses":{"201":{"description":"Event created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}}},"/v1/me/events/{id}":{"get":{"operationId":"getEvent","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:read","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Customer event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEvent","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:update","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["version"],"properties":{"version":{"type":"integer","minimum":1},"card":{"type":"string"},"handwriting":{"type":"string"},"name":{"type":"string"},"purpose":{"type":"string"},"sharedContext":{"type":"string"},"tone":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"409":{"description":"Version or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteEventData","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:delete","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Eligible event personal data deleted"},"409":{"description":"Event cannot yet be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/events/{id}/recipients":{"post":{"operationId":"addEventRecipients","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"recipient:write","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["recipients","version"],"properties":{"recipients":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/EventRecipientInput"}},"version":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Event with added recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}}},"/v1/me/events/{eventId}/recipients/{recipientId}/address-request":{"post":{"operationId":"requestRecipientAddress","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"address-request:send","parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"recipientId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Private address request created and delivery attempted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/me/events/{id}/draft-letters":{"post":{"operationId":"draftEventLetters","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"letter:draft","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Event with AI drafts requiring review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}}},"/v1/me/events/{eventId}/recipients/{recipientId}/approve":{"post":{"operationId":"approveEventLetter","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"letter:approve","parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"recipientId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"message":{"type":"string","minLength":1,"maxLength":320},"version":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Event with approved letter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}}},"/v1/me/events/{id}/publish":{"post":{"operationId":"publishEvent","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:publish","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Frozen campaign draft and human review URL","content":{"application/json":{"schema":{"type":"object","required":["draft","event","reviewUrl"],"properties":{"draft":{"$ref":"#/components/schemas/CampaignDraft"},"event":{"$ref":"#/components/schemas/Event"},"reviewUrl":{"type":"string","format":"uri"}}}}}}}}},"/v1/me/campaign-drafts":{"get":{"operationId":"listCampaignDrafts","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:read","responses":{"200":{"description":"Customer-owned campaign drafts","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CampaignDraft"}}}}}}}}},"post":{"operationId":"createLetterDraft","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"letter:draft","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignQuoteRequest"}}}},"responses":{"201":{"description":"Customer-owned editable letter draft and review URL","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CampaignDraft"},{"type":"object","required":["reviewUrl"],"properties":{"reviewUrl":{"type":"string","format":"uri"}}}]}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/campaign-drafts/{id}":{"get":{"operationId":"getCampaignDraft","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"event:read","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Editable customer campaign draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDraft"}}}}}},"patch":{"operationId":"updateCampaignDraft","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"letter:approve","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["input","version"],"properties":{"input":{"$ref":"#/components/schemas/CampaignQuoteRequest"},"version":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Updated campaign draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDraft"}}}}}}},"/v1/me/campaign-drafts/{id}/payment":{"post":{"operationId":"prepareCampaignDraftPayment","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"payment:prepare","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmed","method","version"],"properties":{"confirmed":{"const":true},"method":{"type":"string","enum":["card","mpp"]},"version":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Card checkout or MPP payment preparation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPreparation"}}}},"409":{"description":"Draft is stale or locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/campaign-drafts/{id}/unlock":{"post":{"operationId":"unlockCampaignDraftPayment","security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"x-inkwire-capability":"payment:prepare","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Editable campaign draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDraft"}}}}}}},"/v1/me/agent-delegations":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]}],"responses":{"200":{"description":"Redacted delegations owned by the current customer","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentDelegation"}}}}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"security":[{"clerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["agentKeyId","scopes"],"properties":{"agentKeyId":{"type":"string","format":"uuid"},"expiresInSeconds":{"type":"integer","minimum":300,"maximum":2592000,"default":86400},"scopes":{"type":"array","minItems":1,"items":{"type":"string","enum":["account:read","event:create","event:read","event:update","recipient:write","address-request:send","letter:draft","letter:approve","event:publish","payment:prepare","event:delete"]}}}}}}},"responses":{"201":{"description":"Delegation created; token is returned once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDelegation"}}}},"404":{"description":"Agent key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/agent-delegations/{id}":{"delete":{"security":[{"clerkSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Delegation revoked"},"404":{"description":"Delegation not found for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/orders":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Cursor-paginated order history for the current customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountOrderList"}}}},"400":{"description":"Invalid pagination cursor or limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Customer accounts are not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/orders/{id}":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Customer-owned order, exact letter content, and status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountOrderDetail"}}}},"400":{"description":"Invalid order ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Customer accounts are not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/campaigns":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Cursor-paginated campaign history for the current customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCampaignList"}}}},"400":{"description":"Invalid pagination cursor or limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Customer accounts are not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/campaigns/{id}":{"get":{"security":[{"clerkSession":[]},{"clerkSessionCookie":[]},{"agentKey":[],"agentDelegation":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Customer-owned mailing and exact per-letter details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCampaignDetail"}}}},"400":{"description":"Invalid campaign ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campaign not found for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Customer accounts are not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/campaigns/{id}/claim":{"post":{"description":"Exchanges a one-time private receipt token for durable ownership by the signed-in customer. Repeating the claim as the same owner is idempotent.","security":[{"clerkSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["claimToken"],"properties":{"claimToken":{"type":"string","minLength":32,"maxLength":200,"writeOnly":true}}}}}},"responses":{"200":{"description":"Claimed customer-owned mailing receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCampaignDetail"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campaign or claim token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quotes":{"post":{"description":"A valid Clerk session is optional. When present, the quote and resulting MPP order belong to that customer.","security":[{},{"clerkSession":[]},{"clerkSessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardRequest"}}}},"responses":{"201":{"description":"Validated quote with message review and approval hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicQuote"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campaign-quotes":{"post":{"description":"A valid Clerk session is optional. When present, the quote and resulting MPP campaign belong to that customer.","security":[{},{"clerkSession":[]},{"clerkSessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignQuoteRequest"}}}},"responses":{"201":{"description":"Validated campaign quote with all rendered messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaignQuote"}}}},"400":{"description":"Invalid recipient, template, or rendered message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid Clerk session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campaigns":{"post":{"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovedQuote"}}}},"responses":{"201":{"description":"Immutable campaign draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreation"}}}},"409":{"description":"Expired quote or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campaigns/{id}/preflight":{"get":{"description":"Read-only readiness check. Call before presenting or attempting payment.","security":[{"campaignToken":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"X-Campaign-Token","required":true,"description":"Campaign token returned when the campaign draft was created.","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign payment and fulfillment readiness","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPreflight"}}}},"401":{"description":"Campaign token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campaigns/{id}/send":{"post":{"security":[{"campaignToken":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}},{"in":"header","name":"X-Campaign-Token","required":true,"description":"Campaign token returned when the campaign draft was created.","schema":{"type":"string"}}],"x-payment-info":{"offers":[{"amount":"quoted campaign total","currency":"usd","intent":"charge","method":"tempo","network":"tempo"},{"amount":"quoted campaign total","currency":"usd","intent":"charge","method":"stripe"}]},"responses":{"200":{"description":"Previously submitted campaign replayed without duplicate mail","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Paid campaign queued for fulfillment","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Campaign token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"MPP Payment Required","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"410":{"description":"MPP handoff was canceled; prepare a replacement handoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/campaigns/{id}":{"get":{"security":[{"bearerToken":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Private per-recipient campaign status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaign"}}}},"401":{"description":"Read token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes":{"post":{"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovedQuote"}}}},"x-payment-info":{"offers":[{"amount":"399","currency":"usd","intent":"charge","method":"tempo","network":"tempo"},{"amount":"399","currency":"usd","intent":"charge","method":"stripe"}]},"responses":{"200":{"description":"Idempotent order replay","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Paid TEST card queued","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"MPP Payment Required","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}}}}},"/v1/notes/{id}":{"get":{"security":[{"bearerToken":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Private order status","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Read token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}