{"openapi":"3.1.0","info":{"title":"Carte API","version":"1.0.0","description":"Carte is a typed, addressable mailbox for businesses. Authenticate with a `ck_live_` API key as a Bearer token."},"servers":[{"url":"https://api.carte.sh"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ck_live_…"}},"schemas":{"PublicProfile":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string"},"accepting_drops":{"type":"boolean"},"verified_domains":{"type":"array","items":{"type":"string"}}},"required":["handle","display_name","accepting_drops","verified_domains"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Message":{"type":"object","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"in_reply_to":{"type":["string","null"]},"from":{"type":"object","properties":{"party":{"$ref":"#/components/schemas/Party"},"actor":{"$ref":"#/components/schemas/Actor"}},"required":["party","actor"]},"to":{"type":"object","properties":{"party":{"$ref":"#/components/schemas/Party"},"target":{"$ref":"#/components/schemas/Target"}},"required":["party","target"]},"type":{"type":["string","null"]},"subject":{"type":["string","null"]},"note":{"type":["string","null"]},"json":{},"json_sha256":{"type":["string","null"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"validation":{"type":"object","properties":{"status":{"type":"string","enum":["passed","failed","not_applicable"]},"errors":{"type":"array","items":{}}},"required":["status","errors"]},"received_at":{"type":"string"},"content_hash":{"type":"string"},"receipt_url":{"type":"string"},"idempotency_key":{"type":["string","null"]}},"required":["id","thread_id","in_reply_to","from","to","type","subject","note","json_sha256","files","validation","received_at","content_hash","receipt_url"]},"Party":{"type":"object","properties":{"kind":{"type":"string","enum":["handle","domain"]},"handle":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string"},"verified_domains":{"type":"array","items":{"type":"string"},"description":"Handles only: domains the business has verified (Google Workspace sign-in today)."}},"required":["kind","display_name"],"description":"Who a message is from or to, in the business sense: a claimed handle, or an unclaimed organisation identified by its email domain (a consumer mailbox is identified by its address)."},"Actor":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","mailbox"]},"id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"verified":{"type":"boolean"},"provider":{"type":"string"},"segment":{"type":["string","null"],"description":"The actor's address segment within its business (`bob` in `acme/bob`), when it has one."}},"required":["kind","id","name","email","verified","provider","segment"],"description":"The hand that sent the message on behalf of the party: a person (Google), an agent (API key under an agent profile) or a mailbox (email-in, verified by DKIM)."},"Target":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["member","agent","unknown"]},"id":{"type":["string","null"]},"segment":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["kind","id","segment","name"],"description":"Where inside the receiving business the message was addressed (`acme/bob` → segment `bob`): a member, an agent, or an unknown segment that still landed in the inbox. Routing, never privacy: every member reads the whole inbox."},"File":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"number"},"sha256":{"type":["string","null"]},"download_url":{"type":"string"},"download_expires_at":{"type":"string"}},"required":["id","filename","content_type","size_bytes","sha256"]},"Me":{"type":"object","properties":{"business":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"display_name":{"type":"string"},"verified_domains":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"}},"required":["id","handle","display_name","verified_domains","created_at"]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scope":{"type":"string","enum":["read","read_write"]}},"required":["id","name","scope"]},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"segment":{"type":["string","null"],"description":"This agent's address inside the business: `<handle>/<segment>`."}},"required":["id","name","description","segment"]},"addresses":{"type":"object","properties":{"drop_url":{"type":"string"},"email":{"type":"string"}},"required":["drop_url","email"]},"usage":{"type":"object","properties":{"messages_this_month":{"type":"number"},"storage_bytes":{"type":"number"}},"required":["messages_this_month","storage_bytes"]},"keys_count":{"type":"number"}},"required":["business","key","agent","addresses","usage","keys_count"]},"MessagePage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]},"Thread":{"type":"object","properties":{"thread_id":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"]},"hidden":{"type":"number"}},"required":["thread_id","data","next_cursor","hidden"]},"DownloadUrl":{"type":"object","properties":{"download_url":{"type":"string"},"expires_at":{"type":"string"}},"required":["download_url","expires_at"]},"SendMessageRequest":{"type":"object","properties":{"to":{"type":"string","minLength":1,"description":"Recipient address: a handle (`acme`) or a member or agent inside it (`acme/bob`, `acme/finance-agent`). An unknown segment still delivers to the business. Optional when `in_reply_to` is set (the recipient is the other party of that message); if given it must match."},"in_reply_to":{"type":"string","description":"Reply to this message (msg_…). You must be a party of it. The reply joins its thread."},"type":{"type":["string","null"],"maxLength":80},"subject":{"type":["string","null"],"maxLength":200},"note":{"type":["string","null"],"maxLength":10000},"json":{},"files":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"upload_ids from POST /uploads"}}},"Upload":{"type":"object","properties":{"upload_id":{"type":"string"},"upload_url":{"type":"string"},"method":{"type":"string","enum":["PUT"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string"}},"required":["upload_id","upload_url","method","headers","expires_at"]},"CreateUploadRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content_type":{"type":"string","maxLength":120},"size_bytes":{"type":"integer","minimum":0}},"required":["filename","size_bytes"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"target":{"type":["string","null"],"description":"When set, only messages addressed to this segment (`<handle>/<target>`) are delivered."},"created_at":{"type":"string"}},"required":["id","url","active","target","created_at"]},"WebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string"}},"required":["secret"]}]},"CreateWebhookRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"target":{"type":["string","null"],"minLength":2,"maxLength":32}},"required":["url"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string"},"attempt":{"type":"number"},"status_code":{"type":["number","null"]},"response_ms":{"type":["number","null"]},"error":{"type":["string","null"]},"attempted_at":{"type":"string"}},"required":["id","message_id","attempt","status_code","response_ms","error","attempted_at"]},"Agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"segment":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","name","description","segment","created_at"],"description":"An agent of the business: the identity behind API keys. `segment` is its address inside the business (`<handle>/<segment>`)."},"UpdateAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":["string","null"],"maxLength":500},"segment":{"type":["string","null"],"maxLength":32}}},"InboxSchema":{"type":"object","properties":{"schema":{"type":["object","null"],"additionalProperties":{}}},"required":["schema"]},"SenderBlock":{"type":"object","properties":{"id":{"type":"string"},"user_id":{"type":["string","null"]},"email_domain":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","user_id","email_domain","created_at"]},"ContactPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]},"Contact":{"type":"object","properties":{"id":{"type":["string","null"],"description":"ctc_… when saved; null for a party only seen in the ledger"},"party":{"$ref":"#/components/schemas/Party"},"saved":{"type":"boolean"},"label":{"type":["string","null"]},"notes":{"type":["string","null"]},"can_initiate":{"type":"boolean","description":"True for handles. Unclaimed parties can only be replied to."},"blocked":{"type":"boolean"},"activity":{"$ref":"#/components/schemas/ContactActivity"}},"required":["id","party","saved","label","notes","can_initiate","blocked","activity"],"description":"An address-book entry: a party (never a person), the owner's label and notes, and activity derived from the ledger."},"ContactActivity":{"type":["object","null"],"properties":{"first_seen_at":{"type":"string"},"last_seen_at":{"type":"string"},"last_direction":{"type":"string","enum":["in","out"]},"messages_in":{"type":"number"},"messages_out":{"type":"number"},"types":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"$ref":"#/components/schemas/ContactActor"}}},"required":["first_seen_at","last_seen_at","last_direction","messages_in","messages_out","types","actors"],"description":"Derived from the ledger: what this business has exchanged with the party. Actors are the hands seen behind the party on inbound messages."},"ContactActor":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","mailbox"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["kind","name","email"]},"SaveContactRequest":{"type":"object","properties":{"handle":{"type":"string"},"domain":{"type":"string","description":"An email domain, or a consumer address"},"label":{"type":["string","null"],"maxLength":80},"notes":{"type":["string","null"],"maxLength":4000}}},"UpdateContactRequest":{"type":"object","properties":{"label":{"type":["string","null"],"maxLength":80},"notes":{"type":["string","null"],"maxLength":4000},"archived":{"type":"boolean"}}},"HandleSearch":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string"}},"required":["handle","display_name"]}}},"required":["data"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Health check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"db":{"type":"string"}},"required":["ok","db"]}}}}}}},"/v1/public/{handle}":{"get":{"tags":["public"],"summary":"Public profile for a handle","parameters":[{"schema":{"type":"string"},"required":true,"name":"handle","in":"path"}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProfile"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/receipts/{token}":{"get":{"tags":["public"],"summary":"Public receipt","description":"The envelope without the JSON body and without download URLs.","parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"tags":["account"],"summary":"Business profile for this key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inbox":{"get":{"tags":["messages"],"summary":"List inbox messages, newest first","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"ISO 8601 timestamp; only messages received at or after"},"required":false,"description":"ISO 8601 timestamp; only messages received at or after","name":"since","in":"query"},{"schema":{"type":"string"},"required":false,"name":"until","in":"query"},{"schema":{"type":"string","description":"Sender handle or email address"},"required":false,"description":"Sender handle or email address","name":"from","in":"query"},{"schema":{"type":"string","description":"Only messages addressed to this segment of your business (`bob` for `acme/bob`)"},"required":false,"description":"Only messages addressed to this segment of your business (`bob` for `acme/bob`)","name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["passed","failed","not_applicable"]},"required":false,"name":"validation","in":"query"},{"schema":{"type":"string","description":"Only messages in this thread (thr_…)"},"required":false,"description":"Only messages in this thread (thr_…)","name":"thread","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Default 50, max 200"},"required":false,"description":"Default 50, max 200","name":"limit","in":"query"}],"responses":{"200":{"description":"Page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagePage"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outbox":{"get":{"tags":["messages"],"summary":"List messages sent by this business","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"ISO 8601 timestamp; only messages received at or after"},"required":false,"description":"ISO 8601 timestamp; only messages received at or after","name":"since","in":"query"},{"schema":{"type":"string"},"required":false,"name":"until","in":"query"},{"schema":{"type":"string","description":"Sender handle or email address"},"required":false,"description":"Sender handle or email address","name":"from","in":"query"},{"schema":{"type":"string","description":"Only messages addressed to this segment of your business (`bob` for `acme/bob`)"},"required":false,"description":"Only messages addressed to this segment of your business (`bob` for `acme/bob`)","name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["passed","failed","not_applicable"]},"required":false,"name":"validation","in":"query"},{"schema":{"type":"string","description":"Only messages in this thread (thr_…)"},"required":false,"description":"Only messages in this thread (thr_…)","name":"thread","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Default 50, max 200"},"required":false,"description":"Default 50, max 200","name":"limit","in":"query"}],"responses":{"200":{"description":"Page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagePage"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/messages/{id}":{"get":{"tags":["messages"],"summary":"Get one message","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/threads/{id}":{"get":{"tags":["messages"],"summary":"Get a thread, oldest first","description":"Every message in the thread (thr_…). Your business must be a party of it. Threads have two parties and are flat: `in_reply_to` records the exact parent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Thread"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/{id}":{"get":{"tags":["messages"],"summary":"Fresh signed download URL for a file","description":"With `Accept: application/json` returns `{ download_url, expires_at }`; otherwise redirects (302) to the signed URL.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Signed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}}},"302":{"description":"Redirect to the signed URL"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/messages":{"post":{"tags":["messages"],"summary":"Send a message, or reply to one","description":"JSON mode (`application/json`): `{ to?, in_reply_to?, type?, subject?, note?, json?, files?: [upload_id] }`. Multipart mode (`multipart/form-data`): fields `to`, `in_reply_to`, `type`, `subject`, `note`, `json` (string) and one or more `file` parts (≤ 25 MB each). With `in_reply_to` the recipient is the other party of that message and `to` may be omitted. Honours `Idempotency-Key` (24h).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}},"multipart/form-data":{"schema":{"type":"object","properties":{"to":{"type":"string"},"in_reply_to":{"type":"string"},"type":{"type":"string"},"subject":{"type":"string"},"note":{"type":"string"},"json":{"type":"string"},"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The message envelope (the receipt)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uploads":{"post":{"tags":["messages"],"summary":"Create a presigned upload for one file","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadRequest"}}}},"responses":{"201":{"description":"Presigned upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List webhooks","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["webhooks"],"summary":"Create a webhook","description":"Returns the signing `secret` once. With `target`, the webhook only fires for messages addressed to that segment of your business (`<handle>/<target>`).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"get":{"tags":["webhooks"],"summary":"Get a webhook","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["webhooks"],"summary":"Delete a webhook","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/test":{"post":{"tags":["webhooks"],"summary":"Send a test event","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"},"job_id":{"type":"string"}},"required":["queued","job_id"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["webhooks"],"summary":"Delivery log","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents":{"get":{"tags":["agents"],"summary":"List the business's agents","description":"Every agent with its segment, so a caller can address a colleague agent as `<handle>/<segment>`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}":{"get":{"tags":["agents"],"summary":"Get an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["agents"],"summary":"Update an agent","description":"Change the name, description or address segment. Segments are 2–32 lowercase letters, digits or hyphens and unique within the business across members and agents; `null` clears it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentRequest"}}}},"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Segment taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inbox/schema":{"get":{"tags":["inbox"],"summary":"Get the inbox JSON Schema","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxSchema"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["inbox"],"summary":"Set (or clear with null) the inbox JSON Schema","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxSchema"}}}},"responses":{"200":{"description":"Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxSchema"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/blocks":{"get":{"tags":["blocks"],"summary":"List blocked senders","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Blocks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SenderBlock"}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["blocks"],"summary":"Block a sender by user id or email domain","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"email_domain":{"type":"string"}}}}}},"responses":{"201":{"description":"Block","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderBlock"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/blocks/{id}":{"delete":{"tags":["blocks"],"summary":"Remove a block","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts":{"get":{"tags":["contacts"],"summary":"List contacts","description":"Saved contacts merged with every party this business has exchanged messages with, newest activity first. Saved contacts with no messages yet come last.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Prefix on handle, domain or label; substring on name"},"required":false,"description":"Prefix on handle, domain or label; substring on name","name":"q","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Only saved contacts"},"required":false,"description":"Only saved contacts","name":"saved","in":"query"},{"schema":{"type":"string","description":"Only parties that have sent this type"},"required":false,"description":"Only parties that have sent this type","name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPage"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["contacts"],"summary":"Save a contact","description":"Save a party by handle or domain with an optional label and notes. Saving a party that is already saved updates it; saving an archived one un-archives it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveContactRequest"}}}},"responses":{"201":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/by-party":{"get":{"tags":["contacts"],"summary":"What this business knows about a party","description":"Look up a party by handle or domain. 404 when the handle does not exist, or the domain is neither saved nor seen.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"handle","in":"query"},{"schema":{"type":"string","description":"An email domain, or a consumer address"},"required":false,"description":"An email domain, or a consumer address","name":"domain","in":"query"}],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}":{"get":{"tags":["contacts"],"summary":"Get a saved contact","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["contacts"],"summary":"Update a saved contact","description":"Change the label, the notes, or archive it. Contacts are never deleted; an archived contact leaves the list and can be saved again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequest"}}}},"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/handles":{"get":{"tags":["contacts"],"summary":"Search the handle directory","description":"Prefix search over every claimed handle. Use it to find a recipient you are not sure of; `GET /public/{handle}` resolves an exact handle without auth.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleSearch"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}