@pidgeon-ai/sdk 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -366,12 +366,18 @@ type AgentVerified = {
     address: string;
     identity_id: string;
     sign_in_url: string;
+    api_key: string;
+    api_key_id: string;
 };
 type Identity = {
     id: string;
     email: string;
     local_part: string;
     domain: string;
+    /**
+     * Pass this to POST /identities to add another address here.
+     */
+    domain_id: string;
     display_name: string | null;
     /**
      * human, team, application, workflow or agent.
@@ -462,7 +468,7 @@ type Message = {
         downloadable: boolean;
     }>;
     /**
-     * The calendar part this message carried, or null. See `prd/calendar.md`.
+     * The calendar part this message carried, or null — the invitation, who was asked, and what they answered.
      */
     invitation: {
         method: string | null;
@@ -984,7 +990,7 @@ type Replayed = {
     status: 'pending';
 };
 type Mailbox = {
-    folder: 'inbox' | 'starred' | 'sent' | 'drafts' | 'scheduled' | 'snoozed' | 'archive' | 'spam' | 'trash';
+    folder: 'inbox' | 'starred' | 'sent' | 'drafts' | 'scheduled' | 'snoozed' | 'archive' | 'spam' | 'trash' | 'unauthenticated';
     /**
      * Null where the product does not count that folder. Not zero — zero is a claim.
      */
@@ -1170,7 +1176,13 @@ type Error = {
 };
 type AgentSignUpData = {
     body: {
+        /**
+         * The local part you want on the shared domain.
+         */
         username: string;
+        /**
+         * A person who can be reached. They receive the code that finishes the signup.
+         */
         human_email: string;
         source?: string | null;
     };
@@ -1184,7 +1196,7 @@ type AgentSignUpErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1204,7 +1216,13 @@ type AgentSignUpResponses = {
 type AgentSignUpResponse = AgentSignUpResponses[keyof AgentSignUpResponses];
 type AgentAttachHumanData = {
     body: {
+        /**
+         * From the signup this is finishing.
+         */
         signup_id: string;
+        /**
+         * A person who can be reached. They receive the code that finishes the signup.
+         */
         human_email: string;
     };
     path?: never;
@@ -1217,7 +1235,7 @@ type AgentAttachHumanErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1237,6 +1255,9 @@ type AgentAttachHumanResponses = {
 type AgentAttachHumanResponse = AgentAttachHumanResponses[keyof AgentAttachHumanResponses];
 type AgentVerifyData = {
     body: {
+        /**
+         * From the signup this is finishing.
+         */
         signup_id: string;
         code: string;
     };
@@ -1250,7 +1271,7 @@ type AgentVerifyErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1273,6 +1294,9 @@ type IdentitiesListData = {
     path?: never;
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
         tenant_id?: string;
     };
@@ -1284,7 +1308,7 @@ type IdentitiesListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1309,13 +1333,49 @@ type IdentitiesListResponses = {
 type IdentitiesListResponse = IdentitiesListResponses[keyof IdentitiesListResponses];
 type IdentitiesCreateData = {
     body: {
-        domain_id: string;
-        local_part: string;
+        /**
+         * From `GET /domains`, or the `domain_id` on any address you already have.
+         */
+        domain_id?: string;
+        /**
+         * A domain name you own, or the shared one. An alternative to `domain_id`.
+         */
+        domain?: string;
+        /**
+         * A whole address — the local part and the domain in one. An alternative to the other two.
+         */
+        address?: string;
+        /**
+         * Everything before the `@`.
+         */
+        local_part?: string;
+        /**
+         * The name a recipient sees beside the address.
+         */
         display_name?: string | null;
+        /**
+         * Whether it keeps mail. With an inbox what arrives is stored and a person can open it; without one it becomes an event and your webhook fires. Defaults from `type`.
+         */
+        inbox?: boolean;
+        /**
+         * A label for what this address is for. It does not change what the address can do — that is `inbox`.
+         */
         type?: 'human' | 'team' | 'application' | 'workflow' | 'agent';
+        /**
+         * Who answers: a person, software, or both.
+         */
         mode?: 'human' | 'automated' | 'hybrid';
+        /**
+         * When it stops accepting mail. Expiry suspends; it never deletes, so the correspondence survives.
+         */
         expires_at?: string | null;
+        /**
+         * Who it may write to. `reply_only` makes an address structurally unable to start a conversation with a stranger.
+         */
         send_policy?: 'open' | 'reply_only' | 'list';
+        /**
+         * Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
+         */
         tenant_id?: string | null;
     };
     path?: never;
@@ -1328,7 +1388,7 @@ type IdentitiesCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1360,7 +1420,7 @@ type IdentitiesDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1392,7 +1452,7 @@ type IdentitiesGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1412,14 +1472,29 @@ type IdentitiesGetResponses = {
 type IdentitiesGetResponse = IdentitiesGetResponses[keyof IdentitiesGetResponses];
 type IdentitiesUpdateData = {
     body: {
+        /**
+         * The name a recipient sees beside the address.
+         */
         display_name?: string | null;
+        /**
+         * Who answers: a person, software, or both.
+         */
         mode?: 'human' | 'automated' | 'hybrid';
         capabilities?: {
             [key: string]: boolean;
         };
         status?: 'active' | 'suspended' | 'archived';
+        /**
+         * When it stops accepting mail. Expiry suspends; it never deletes, so the correspondence survives.
+         */
         expires_at?: string | null;
+        /**
+         * Who it may write to. `reply_only` makes an address structurally unable to start a conversation with a stranger.
+         */
         send_policy?: 'open' | 'reply_only' | 'list';
+        /**
+         * Your own opaque grouping — a customer id, whatever your side calls it. Never parsed here.
+         */
         tenant_id?: string | null;
     };
     path: {
@@ -1434,7 +1509,7 @@ type IdentitiesUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1468,7 +1543,7 @@ type IdentitiesAccessDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1500,7 +1575,7 @@ type IdentitiesAccessGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1523,6 +1598,9 @@ type IdentitiesAccessCreateData = {
         user_id?: string;
         api_key_id?: string;
         everyone?: true;
+        /**
+         * What a key may do. Give an agent the narrowest one that works.
+         */
         access: 'read' | 'send' | 'admin';
     };
     path: {
@@ -1537,7 +1615,7 @@ type IdentitiesAccessCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1571,7 +1649,7 @@ type IdentitiesSendRulesDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1603,7 +1681,7 @@ type IdentitiesSendRulesGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1638,7 +1716,7 @@ type IdentitiesSendRulesCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1672,7 +1750,7 @@ type IdentitiesReceiveRulesDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1704,7 +1782,7 @@ type IdentitiesReceiveRulesGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1739,7 +1817,7 @@ type IdentitiesReceiveRulesCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1774,7 +1852,7 @@ type IdentitiesSuspendTenantErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1806,7 +1884,7 @@ type LabelsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1831,6 +1909,9 @@ type LabelsListResponses = {
 type LabelsListResponse = LabelsListResponses[keyof LabelsListResponses];
 type LabelsCreateData = {
     body: {
+        /**
+         * The address this belongs to.
+         */
         identity_id: string;
         name: string;
         colour?: string;
@@ -1845,7 +1926,7 @@ type LabelsCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1877,7 +1958,7 @@ type LabelsDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1912,7 +1993,7 @@ type LabelsUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1946,7 +2027,7 @@ type ThreadsLabelsDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -1978,7 +2059,7 @@ type ThreadsLabelsGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2017,7 +2098,7 @@ type ThreadsLabelsCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2045,6 +2126,9 @@ type MessagesListInThreadData = {
     path?: never;
     query: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
         thread_id: string;
     };
@@ -2056,7 +2140,7 @@ type MessagesListInThreadErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2081,14 +2165,41 @@ type MessagesListInThreadResponses = {
 type MessagesListInThreadResponse = MessagesListInThreadResponses[keyof MessagesListInThreadResponses];
 type MessagesSendData = {
     body: {
+        /**
+         * An address on a domain you own, and one this key may send from.
+         */
         from: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to: string | Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: string | Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: string | Array<string>;
+        /**
+         * Left off a reply, where the thread already has one.
+         */
         subject?: string;
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string;
+        /**
+         * The rich body. Sanitised on the way in; scripts and remote content are removed.
+         */
         html?: string;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
+        /**
+         * The message being answered. Keeps the conversation together in the recipient’s client too.
+         */
         in_reply_to?: string | null;
     };
     path?: never;
@@ -2101,7 +2212,7 @@ type MessagesSendErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2112,10 +2223,10 @@ type MessagesSendErrors = {
 type MessagesSendError = MessagesSendErrors[keyof MessagesSendErrors];
 type MessagesSendResponses = {
     /**
-     * The sent message.
+     * Accepted.
      */
-    201: {
-        data: Message;
+    202: {
+        data: Sent;
     };
 };
 type MessagesSendResponse = MessagesSendResponses[keyof MessagesSendResponses];
@@ -2125,7 +2236,7 @@ type MessagesSearchData = {
     query: {
         identity_id: string;
         q?: string;
-        in?: 'inbox' | 'starred' | 'sent' | 'drafts' | 'scheduled' | 'snoozed' | 'archive' | 'spam' | 'trash';
+        in?: 'inbox' | 'starred' | 'sent' | 'drafts' | 'scheduled' | 'snoozed' | 'archive' | 'spam' | 'trash' | 'unauthenticated';
         from?: string;
         to?: string;
         has_attachment?: string;
@@ -2142,7 +2253,7 @@ type MessagesSearchErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2180,7 +2291,7 @@ type MessagesActErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2212,7 +2323,7 @@ type MessagesUndoErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2244,7 +2355,7 @@ type MessagesGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2280,7 +2391,7 @@ type MessagesUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2300,11 +2411,29 @@ type MessagesUpdateResponses = {
 type MessagesUpdateResponse = MessagesUpdateResponses[keyof MessagesUpdateResponses];
 type MessagesReplyData = {
     body: {
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string;
+        /**
+         * The rich body. Sanitised on the way in; scripts and remote content are removed.
+         */
         html?: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to?: Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: Array<string>;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
     };
     path: {
@@ -2319,7 +2448,7 @@ type MessagesReplyErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2339,11 +2468,29 @@ type MessagesReplyResponses = {
 type MessagesReplyResponse = MessagesReplyResponses[keyof MessagesReplyResponses];
 type MessagesReplyAllData = {
     body: {
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string;
+        /**
+         * The rich body. Sanitised on the way in; scripts and remote content are removed.
+         */
         html?: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to?: Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: Array<string>;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
     };
     path: {
@@ -2358,7 +2505,7 @@ type MessagesReplyAllErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2378,11 +2525,29 @@ type MessagesReplyAllResponses = {
 type MessagesReplyAllResponse = MessagesReplyAllResponses[keyof MessagesReplyAllResponses];
 type MessagesForwardData = {
     body: {
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string;
+        /**
+         * The rich body. Sanitised on the way in; scripts and remote content are removed.
+         */
         html?: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to?: Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: Array<string>;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
     };
     path: {
@@ -2397,7 +2562,7 @@ type MessagesForwardErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2429,7 +2594,7 @@ type MessagesRawErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2450,7 +2615,17 @@ type ThreadsListData = {
     path?: never;
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
+        identity_id?: string;
+        status?: 'open' | 'waiting' | 'resolved' | 'human_review';
+        owner_type?: 'human' | 'automation' | 'agent';
+        /**
+         * A person’s id, or `unassigned` for the queue nobody has taken.
+         */
+        assignee_id?: string | 'unassigned';
     };
     url: '/threads';
 };
@@ -2460,7 +2635,7 @@ type ThreadsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2497,7 +2672,7 @@ type ThreadsGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2533,7 +2708,7 @@ type ThreadsUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2556,6 +2731,9 @@ type DomainsListData = {
     path?: never;
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
     };
     url: '/domains';
@@ -2566,7 +2744,7 @@ type DomainsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2591,6 +2769,9 @@ type DomainsListResponses = {
 type DomainsListResponse = DomainsListResponses[keyof DomainsListResponses];
 type DomainsCreateData = {
     body: {
+        /**
+         * A domain name you own, or the shared one. An alternative to `domain_id`.
+         */
         domain: string;
     };
     path?: never;
@@ -2603,7 +2784,7 @@ type DomainsCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2635,7 +2816,7 @@ type DomainsZoneFileErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2670,7 +2851,7 @@ type DomainsGetSetupLinkErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2702,7 +2883,7 @@ type DomainsVerifyErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2734,7 +2915,7 @@ type DomainsDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2766,7 +2947,7 @@ type DomainsGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2800,7 +2981,7 @@ type DomainsUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2832,7 +3013,7 @@ type RoutingListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2884,7 +3065,7 @@ type RoutingCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2916,7 +3097,7 @@ type RoutingDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2950,7 +3131,7 @@ type RoutingUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -2982,7 +3163,7 @@ type MailboxesListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3021,7 +3202,7 @@ type MailboxesChangesErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3060,7 +3241,7 @@ type MailboxesEmptyTrashErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3086,6 +3267,9 @@ type MailboxesListFolderData = {
     query: {
         identity_id: string;
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
         label_id?: string;
     };
@@ -3097,7 +3281,7 @@ type MailboxesListFolderErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3132,7 +3316,7 @@ type KeysListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3159,7 +3343,13 @@ type KeysCreateData = {
     body: {
         name: string;
         identity_ids: Array<string>;
+        /**
+         * What a key may do. Give an agent the narrowest one that works.
+         */
         access?: 'read' | 'send' | 'admin';
+        /**
+         * When it stops accepting mail. Expiry suspends; it never deletes, so the correspondence survives.
+         */
         expires_at?: string | null;
     };
     path?: never;
@@ -3172,7 +3362,7 @@ type KeysCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3204,7 +3394,7 @@ type KeysRevokeErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3236,7 +3426,7 @@ type KeysGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3270,7 +3460,7 @@ type KeysUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3302,7 +3492,7 @@ type AppPasswordsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3327,6 +3517,9 @@ type AppPasswordsListResponses = {
 type AppPasswordsListResponse = AppPasswordsListResponses[keyof AppPasswordsListResponses];
 type AppPasswordsCreateData = {
     body: {
+        /**
+         * The address this belongs to.
+         */
         identity_id: string;
         name: string;
     };
@@ -3340,7 +3533,7 @@ type AppPasswordsCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3372,7 +3565,7 @@ type AppPasswordsRevokeErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3402,7 +3595,7 @@ type WorkspaceGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3432,7 +3625,7 @@ type WorkspaceMembersErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3460,6 +3653,9 @@ type EventsListData = {
     path?: never;
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
         type?: string;
         identity_id?: string;
@@ -3473,7 +3669,7 @@ type EventsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3510,7 +3706,7 @@ type EventsGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3533,6 +3729,9 @@ type WebhooksListData = {
     path?: never;
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
     };
     url: '/webhooks';
@@ -3543,7 +3742,7 @@ type WebhooksListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3568,7 +3767,13 @@ type WebhooksListResponses = {
 type WebhooksListResponse = WebhooksListResponses[keyof WebhooksListResponses];
 type WebhooksCreateData = {
     body: {
+        /**
+         * Where we POST. HTTPS, and it has to answer within a few seconds.
+         */
         url: string;
+        /**
+         * The address this belongs to.
+         */
         identity_id?: string | null;
         event_types?: Array<'message.received' | 'message.sent' | 'message.delivered' | 'message.bounced' | 'message.rejected' | 'message.complained' | 'message.spam' | 'message.invitation' | 'message.archived' | 'message.deleted' | 'calendar.event.created' | 'calendar.event.updated' | 'calendar.event.deleted' | 'calendar.event.starting' | 'calendar.event.ending' | 'calendar.event.responded' | 'thread.created' | 'thread.updated' | 'thread.assigned' | 'thread.unassigned' | 'identity.created' | 'identity.updated' | 'identity.suspended' | 'identity.transferred' | 'domain.verified'>;
     };
@@ -3582,7 +3787,7 @@ type WebhooksCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3614,7 +3819,7 @@ type WebhooksDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3646,7 +3851,7 @@ type WebhooksGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3680,7 +3885,7 @@ type WebhooksUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3712,7 +3917,7 @@ type WebhooksGetHeadersErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3748,7 +3953,7 @@ type WebhooksUpdateHeadersErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3781,7 +3986,7 @@ type WebhooksDeliveriesErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3818,7 +4023,7 @@ type WebhooksReplayErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3853,7 +4058,7 @@ type MessagesRespondToInvitationErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3891,7 +4096,7 @@ type CalendarGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3911,6 +4116,9 @@ type CalendarGetResponses = {
 type CalendarGetResponse = CalendarGetResponses[keyof CalendarGetResponses];
 type CalendarUpdateData = {
     body: {
+        /**
+         * An IANA name, like `Europe/Lisbon`. The times above are read in it.
+         */
         timezone: string;
     };
     headers?: {
@@ -3931,7 +4139,7 @@ type CalendarUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3956,6 +4164,9 @@ type CalendarListEventsData = {
     };
     query?: {
         limit?: number;
+        /**
+         * From a previous page’s `next_cursor`. Opaque — do not parse it.
+         */
         cursor?: string;
     };
     url: '/identities/{id}/calendar/events';
@@ -3966,7 +4177,7 @@ type CalendarListEventsErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -3994,6 +4205,9 @@ type CalendarCreateEventData = {
         title: string;
         start: string;
         end: string;
+        /**
+         * An IANA name, like `Europe/Lisbon`. The times above are read in it.
+         */
         timezone?: string | null;
         all_day?: boolean;
         description?: string | null;
@@ -4025,7 +4239,7 @@ type CalendarCreateEventErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4068,7 +4282,7 @@ type CalendarRespondToEventErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4105,7 +4319,7 @@ type CalendarListEventInstancesErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4147,7 +4361,7 @@ type CalendarGetAgendaErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4196,7 +4410,7 @@ type CalendarDeleteEventErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4229,7 +4443,7 @@ type CalendarGetEventErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4252,6 +4466,9 @@ type CalendarUpdateEventData = {
         title?: string;
         start?: string;
         end?: string;
+        /**
+         * An IANA name, like `Europe/Lisbon`. The times above are read in it.
+         */
         timezone?: string;
         all_day?: boolean;
         description?: string | null;
@@ -4295,7 +4512,7 @@ type CalendarUpdateEventErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4328,7 +4545,7 @@ type DraftsListErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4353,14 +4570,38 @@ type DraftsListResponses = {
 type DraftsListResponse = DraftsListResponses[keyof DraftsListResponses];
 type DraftsCreateData = {
     body: {
+        /**
+         * The address this belongs to.
+         */
         identity_id: string;
+        /**
+         * An address on a domain you own, and one this key may send from.
+         */
         from?: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to?: Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: Array<string>;
+        /**
+         * Left off a reply, where the thread already has one.
+         */
         subject?: string | null;
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string | null;
         in_reply_to_message_id?: string | null;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
     };
     path?: never;
@@ -4373,7 +4614,7 @@ type DraftsCreateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4405,7 +4646,7 @@ type DraftsDeleteErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4437,7 +4678,7 @@ type DraftsGetErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4457,12 +4698,33 @@ type DraftsGetResponses = {
 type DraftsGetResponse = DraftsGetResponses[keyof DraftsGetResponses];
 type DraftsUpdateData = {
     body: {
+        /**
+         * An address on a domain you own, and one this key may send from.
+         */
         from?: string;
+        /**
+         * One address or several. A string is accepted for the single case.
+         */
         to?: Array<string>;
+        /**
+         * Copied, and visible to everybody who receives the message.
+         */
         cc?: Array<string>;
+        /**
+         * Copied, and visible to nobody else.
+         */
         bcc?: Array<string>;
+        /**
+         * Left off a reply, where the thread already has one.
+         */
         subject?: string | null;
+        /**
+         * The plain-text body. Send this even when you send `html` — some clients only read it.
+         */
         text?: string | null;
+        /**
+         * Ids from `POST /attachments`, uploaded before the message that carries them. Up to 20.
+         */
         attachment_ids?: Array<string>;
     };
     path: {
@@ -4477,7 +4739,7 @@ type DraftsUpdateErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4509,7 +4771,7 @@ type DraftsSendErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4541,7 +4803,7 @@ type DraftsCancelScheduleErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4575,7 +4837,7 @@ type DraftsScheduleErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4608,7 +4870,7 @@ type DraftsRemoveAttachmentErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4641,7 +4903,7 @@ type MetricsQueryErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4674,7 +4936,7 @@ type AttachmentsUploadErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4706,7 +4968,7 @@ type AttachmentsDownloadUrlErrors = {
      */
     401: Error;
     /**
-     * No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
+     * No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
      */
     404: Error;
     /**
@@ -4753,7 +5015,7 @@ declare const agentAttachHuman: <ThrowOnError extends boolean = false>(options:
 /**
  * Verify an agent with the human’s code
  *
- * Creates the account and the address. Ten wrong codes spend the signup, whatever comes next. It returns no key: the agent asks for one through the account it now belongs to, which is how every other key is made.
+ * Creates the account, the address and a workspace-scoped API key. Ten wrong codes spend the signup, whatever comes next. The key is returned once and never again — store it before doing anything else. It is minted here rather than at signup because this is the call a human has vouched for.
  */
 declare const agentVerify: <ThrowOnError extends boolean = false>(options: Options<AgentVerifyData, ThrowOnError>) => RequestResult<AgentVerifyResponses, AgentVerifyErrors, ThrowOnError>;
 /**
@@ -4891,7 +5153,7 @@ declare const messagesListInThread: <ThrowOnError extends boolean = false>(optio
 /**
  * Send a message
  *
- * Idempotent with an `Idempotency-Key` header.
+ * Idempotent with an `Idempotency-Key` header. Answers `202` with the id, the thread and anything **rejected** — a recipient the address is not allowed to write to is refused here rather than failing later, so read `rejected` before assuming it went.
  */
 declare const messagesSend: <ThrowOnError extends boolean = false>(options: Options<MessagesSendData, ThrowOnError>) => RequestResult<MessagesSendResponses, MessagesSendErrors, ThrowOnError>;
 /**