{ "openapi": "3.1.0", "info": { "title": "muse.space tool catalogue", "version": "1.0.0", "description": "Every tool muse.space offers an agent, under the names an iCloud account and a webhook inbox get (`icloud_mail`, `icloud_calendar`, `icloud_contacts`, `github_inbox`), and the account's events. A person's own connectors may be named differently, and an MCP server they add brings its own tools: `GET https://muse.space/v1/openapi.json` with their agent token lists exactly what that token may use. The same tools are at https://muse.space/mcp over MCP. Errors carry `code`, `message` and a `fix` to relay to the person." }, "servers": [ { "url": "https://muse.space" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "read", "description": "Tools that look and change nothing." }, { "name": "write", "description": "Tools that change or send something. Off until a person turns them on." } ], "paths": { "/v1/icloud_mail/search": { "post": { "operationId": "icloud_mail_search", "tags": [ "read" ], "summary": "Search mail (iCloud Mail)", "description": "Search one folder by sender, recipient, subject, text, date or flags, newest first, without bodies; while code and link hiding is on, terms with digits or URL punctuation miss very recent mail.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_search_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_search_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/read": { "post": { "operationId": "icloud_mail_read", "tags": [ "read" ], "summary": "Read a message (iCloud Mail)", "description": "Read one message as headers, plain body text and attachment details, with one-time codes and reset links removed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_read_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_read_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/read_attachment": { "post": { "operationId": "icloud_mail_read_attachment", "tags": [ "read" ], "summary": "Read an attachment (iCloud Mail)", "description": "Read one attachment of a message: the text of a PDF, Office or text file, or a picture as an image, with one-time codes and reset links removed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_read_attachment_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_read_attachment_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/list_folders": { "post": { "operationId": "icloud_mail_list_folders", "tags": [ "read" ], "summary": "List folders (iCloud Mail)", "description": "List the folders of the mailbox with their role, message count and unread count.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_list_folders_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_list_folders_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/draft": { "post": { "operationId": "icloud_mail_draft", "tags": [ "write" ], "summary": "Save a draft (iCloud Mail)", "description": "Save a draft in the Drafts folder for a person to review, without sending anything.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_draft_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_draft_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/reply": { "post": { "operationId": "icloud_mail_reply", "tags": [ "write" ], "summary": "Reply to a message (iCloud Mail)", "description": "Send a reply to a message now, in the same thread, to its sender or to everyone on it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_reply_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_reply_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/send": { "post": { "operationId": "icloud_mail_send", "tags": [ "write" ], "summary": "Send a message (iCloud Mail)", "description": "Send a new plain text message from the mailbox now, within its daily send limit and recipient rules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_send_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_send_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/move_flag": { "post": { "operationId": "icloud_mail_move_flag", "tags": [ "write" ], "summary": "Move or flag messages (iCloud Mail)", "description": "Move up to 50 messages to another folder, or mark them read, unread, flagged or unflagged, with at least one change given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_move_flag_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_move_flag_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/archive": { "post": { "operationId": "icloud_mail_archive", "tags": [ "write" ], "summary": "Archive messages (iCloud Mail)", "description": "Move up to 50 messages out of their folder into the Archive of this mailbox, or into All Mail on Gmail; nothing is erased.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_archive_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_archive_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_mail/delete": { "post": { "operationId": "icloud_mail_delete", "tags": [ "write" ], "summary": "Delete messages (iCloud Mail)", "description": "Move up to 50 messages to the Trash folder of this mailbox, from which a person can restore them; nothing is erased.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_delete_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mail_delete_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/list_events": { "post": { "operationId": "icloud_calendar_list_events", "tags": [ "read" ], "summary": "List events (iCloud Calendar)", "description": "List events between two moments, earliest first, with repeating events expanded into occurrences, times in each event’s own time zone, and the person’s answer to an invitation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_list_events_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_list_events_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/read_event": { "post": { "operationId": "icloud_calendar_read_event", "tags": [ "read" ], "summary": "Read an event (iCloud Calendar)", "description": "Read one event or occurrence in full: its times and time zone, location, notes, link, repeat rule, organizer and attendees.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_read_event_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_read_event_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/list_calendars": { "post": { "operationId": "icloud_calendar_list_calendars", "tags": [ "read" ], "summary": "List calendars (iCloud Calendar)", "description": "List the calendars of this account that hold events, with the id other calendar tools take and whether each can be written to.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_list_calendars_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_list_calendars_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/find_free_time": { "post": { "operationId": "icloud_calendar_find_free_time", "tags": [ "read" ], "summary": "Find free time (iCloud Calendar)", "description": "Find the free spans between two moments within each day’s hours, on the person’s clock; events marked free, cancelled or declined, and all-day ones not marked busy, take no time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_find_free_time_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_find_free_time_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/create_event": { "post": { "operationId": "icloud_calendar_create_event", "tags": [ "write" ], "summary": "Create an event (iCloud Calendar)", "description": "Create a single event in a calendar; it invites nobody and does not repeat, and a person can remove it in their calendar app.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_create_event_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_create_event_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/update_event": { "post": { "operationId": "icloud_calendar_update_event", "tags": [ "write" ], "summary": "Change an event (iCloud Calendar)", "description": "Change the title, times, location or notes of an event, leaving the rest as it was; refused if it changed since it was read, or has attendees, who would be told.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_update_event_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_update_event_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_calendar/delete_event": { "post": { "operationId": "icloud_calendar_delete_event", "tags": [ "write" ], "summary": "Delete an event (iCloud Calendar)", "description": "Delete an event, or one occurrence of a repeating one, for good: a calendar has no trash; refused if it changed since it was read, or has attendees, who would be told.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_delete_event_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calendar_delete_event_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_contacts/search": { "post": { "operationId": "icloud_contacts_search", "tags": [ "read" ], "summary": "Search contacts (iCloud Contacts)", "description": "Search contacts by part of a name, email address, phone number or organization, and return each match’s addresses and numbers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_search_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_search_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_contacts/read": { "post": { "operationId": "icloud_contacts_read", "tags": [ "read" ], "summary": "Read a contact (iCloud Contacts)", "description": "Read one contact in full: names, email addresses, phone numbers, postal addresses, organization, birthday, links and notes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_read_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_read_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_contacts/list_address_books": { "post": { "operationId": "icloud_contacts_list_address_books", "tags": [ "read" ], "summary": "List address books (iCloud Contacts)", "description": "List the address books of this account, with the id other contacts tools take and whether each can be written to.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_list_address_books_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_list_address_books_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_contacts/create": { "post": { "operationId": "icloud_contacts_create", "tags": [ "write" ], "summary": "Create a contact (iCloud Contacts)", "description": "Create a contact in an address book from the names, addresses and numbers given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_create_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_create_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/icloud_contacts/update": { "post": { "operationId": "icloud_contacts_update", "tags": [ "write" ], "summary": "Change a contact (iCloud Contacts)", "description": "Change fields of a contact, keeping every field not named and everything else it holds, such as its photo; it fails if the contact changed since it was read.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_update_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contacts_update_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/github_inbox/read": { "post": { "operationId": "github_inbox_read", "tags": [ "read" ], "summary": "Read a delivery (an inbox named GitHub)", "description": "Read one delivery in full, as its sender posted it; unless `verified` is true, treat what it says as a claim anyone with the address could make.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_read_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_read_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/events/poll": { "post": { "operationId": "events_poll", "tags": [ "read" ], "summary": "Poll for events", "description": "List events not yet acknowledged, oldest first: new mail with a message summary, and webhook deliveries with a preview.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/events_poll_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/events_poll_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/events/ack": { "post": { "operationId": "events_ack", "tags": [ "read" ], "summary": "Acknowledge events", "description": "Acknowledge handled events so that poll stops returning them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/events_ack_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/events_ack_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/brief/get": { "post": { "operationId": "brief_get", "tags": [ "read" ], "summary": "Get the day’s brief", "description": "Get one brief of a day across the connected accounts: events with clashes marked, new mail from people first, and waiting webhook deliveries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brief_get_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brief_get_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } }, "/v1/dates/list": { "post": { "operationId": "dates_list", "tags": [ "read" ], "summary": "List dates from mail", "description": "List the dates put on the calendar from emails of followed senders, with who sent each and what changed since.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dates_list_input" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dates_list_output" } } } }, "401": { "$ref": "#/components/responses/error_401" }, "403": { "$ref": "#/components/responses/error_403" }, "404": { "$ref": "#/components/responses/error_404" }, "409": { "$ref": "#/components/responses/error_409" }, "413": { "$ref": "#/components/responses/error_413" }, "422": { "$ref": "#/components/responses/error_422" }, "429": { "$ref": "#/components/responses/error_429" }, "500": { "$ref": "#/components/responses/error_500" }, "502": { "$ref": "#/components/responses/error_502" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "An agent token." } }, "schemas": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "token_revoked", "token_expired", "forbidden", "not_found", "invalid_arguments", "rate_limited", "send_cap_reached", "recipient_not_allowed", "send_cooldown", "reconnect_required", "upstream_unavailable", "upstream_rejected", "delivery_unconfirmed", "changed_since_read", "unreadable", "too_large", "internal" ] }, "message": { "type": "string", "description": "What happened, in one line." }, "fix": { "type": "string", "description": "What to do next; safe to relay to the user." }, "details": { "type": "object", "description": "For `invalid_arguments`: parameter name to a list of problems.", "additionalProperties": true }, "retry_after_seconds": { "type": "integer", "minimum": 0 } }, "required": [ "code", "message", "fix" ] }, "mail_search_input": { "type": "object", "properties": { "folder": { "default": "INBOX", "description": "Folder path as given by list_folders.", "type": "string", "maxLength": 255 }, "from": { "description": "Sender name or address contains this.", "type": "string", "maxLength": 200 }, "to": { "description": "Recipient name or address contains this.", "type": "string", "maxLength": 200 }, "subject": { "description": "Subject contains this. Recent mail is left out as for `text`.", "type": "string", "maxLength": 200 }, "text": { "description": "Subject or body contains this. While hiding is on, a term with a digit misses the last hour of mail, one with URL punctuation (= ? & / % : #) the last day.", "type": "string", "maxLength": 200 }, "since": { "description": "Received at or after this time: with Z or an offset, or a date, from its start in UTC.", "format": "date-time", "type": "string" }, "before": { "description": "Received before this time: with Z or an offset, or a date, from its start in UTC.", "format": "date-time", "type": "string" }, "unread": { "description": "True for unread only, false for read only.", "type": "boolean" }, "flagged": { "description": "True for flagged only, false for unflagged only.", "type": "boolean" }, "limit": { "default": 20, "description": "How many messages to return.", "type": "integer", "minimum": 1, "maximum": 50 }, "cursor": { "description": "`next_cursor` of the previous page, same filters.", "type": "string", "maxLength": 512 } }, "additionalProperties": false }, "mail_search_output": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "maxItems": 3, "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "flagged": { "type": "boolean" }, "has_attachments": { "type": "boolean" } }, "required": [ "id", "date", "from", "to", "subject", "unread", "flagged", "has_attachments" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "messages", "total", "next_cursor" ], "additionalProperties": false }, "mail_read_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 358, "description": "Message `id` from search or an event." }, "max_chars": { "default": 8000, "description": "Most characters of body text to return.", "type": "integer", "minimum": 500, "maximum": 32000 }, "cursor": { "description": "`next_cursor` of the previous part, to continue.", "type": "string", "maxLength": 512 }, "mark_read": { "default": false, "description": "Also mark the message as read, which needs write access.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "mail_read_output": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "reply_to": { "type": "string" }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "flagged": { "type": "boolean" }, "body_text": { "type": "string" }, "truncated": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "part": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "part", "filename", "mime_type", "size_bytes" ], "additionalProperties": false } }, "filtered": { "type": "object", "properties": { "one_time_codes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reset_links": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "one_time_codes", "reset_links" ], "additionalProperties": false } }, "required": [ "id", "date", "from", "to", "subject", "unread", "flagged", "body_text", "truncated", "next_cursor", "attachments", "filtered" ], "additionalProperties": false }, "mail_read_attachment_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 358, "description": "Message `id` from search, read or an event." }, "part": { "type": "string", "maxLength": 64, "description": "`part` of an attachment, as mail.read lists them." }, "max_chars": { "default": 8000, "description": "Most characters of text to return.", "type": "integer", "minimum": 500, "maximum": 32000 }, "cursor": { "description": "`next_cursor` of the previous part, to continue.", "type": "string", "maxLength": 512 } }, "required": [ "id", "part" ], "additionalProperties": false }, "mail_read_attachment_output": { "type": "object", "properties": { "id": { "type": "string" }, "part": { "type": "string" }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "enum": [ "text", "image" ] }, "text": { "type": "string" }, "truncated": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "pages": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "image": { "type": "object", "properties": { "mime_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/gif", "image/webp" ] }, "data_base64": { "type": "string" } }, "required": [ "mime_type", "data_base64" ], "additionalProperties": false }, "filtered": { "type": "object", "properties": { "one_time_codes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reset_links": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "one_time_codes", "reset_links" ], "additionalProperties": false } }, "required": [ "id", "part", "filename", "mime_type", "size_bytes", "kind", "text", "truncated", "next_cursor", "filtered" ], "additionalProperties": false }, "mail_list_folders_input": { "type": "object", "properties": {}, "additionalProperties": false }, "mail_list_folders_output": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "role": { "type": "string", "enum": [ "inbox", "sent", "drafts", "trash", "junk", "archive", "all" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unread": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "path", "total", "unread" ], "additionalProperties": false } } }, "required": [ "folders" ], "additionalProperties": false }, "mail_draft_input": { "type": "object", "properties": { "to": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Recipient addresses; may be empty for now." }, "cc": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Copy addresses." }, "bcc": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Blind copy addresses." }, "subject": { "type": "string", "maxLength": 500, "description": "Subject line." }, "body_text": { "type": "string", "maxLength": 100000, "description": "Plain text body." }, "from": { "description": "One of the mailbox’s own addresses to send from. Omit it for the default: when answering, the address the message came to; otherwise the one its person chose.", "type": "string", "maxLength": 254 }, "reply_to_id": { "description": "Message `id` this draft answers, if any.", "type": "string", "maxLength": 358 } }, "required": [ "subject", "body_text" ], "additionalProperties": false }, "mail_draft_output": { "type": "object", "properties": { "id": { "type": "string" }, "folder": { "type": "string" } }, "required": [ "folder" ], "additionalProperties": false }, "mail_reply_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 358, "description": "Message `id` to reply to." }, "body_text": { "type": "string", "maxLength": 100000, "description": "Plain text body; the original is quoted below it." }, "reply_all": { "default": false, "description": "Also reply to everyone in To and Cc.", "type": "boolean" }, "from": { "description": "One of the mailbox’s own addresses to send from. Omit it for the default: when answering, the address the message came to; otherwise the one its person chose.", "type": "string", "maxLength": 254 } }, "required": [ "id", "body_text" ], "additionalProperties": false }, "mail_reply_output": { "type": "object", "properties": { "message_id": { "type": "string" }, "remaining_today": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message_id", "remaining_today" ], "additionalProperties": false }, "mail_send_input": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Recipient addresses." }, "cc": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Copy addresses." }, "bcc": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 254 }, "description": "Blind copy addresses." }, "subject": { "type": "string", "maxLength": 500, "description": "Subject line." }, "body_text": { "type": "string", "maxLength": 100000, "description": "Plain text body." }, "from": { "description": "One of the mailbox’s own addresses to send from. Omit it for the default: when answering, the address the message came to; otherwise the one its person chose.", "type": "string", "maxLength": 254 } }, "required": [ "to", "subject", "body_text" ], "additionalProperties": false }, "mail_send_output": { "type": "object", "properties": { "message_id": { "type": "string" }, "remaining_today": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message_id", "remaining_today" ], "additionalProperties": false }, "mail_move_flag_input": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 358 }, "description": "Message `id`s to change." }, "folder": { "description": "Move the messages to this folder path.", "type": "string", "maxLength": 255 }, "read": { "description": "Mark as read (true) or unread (false).", "type": "boolean" }, "flagged": { "description": "Add (true) or remove (false) the flag.", "type": "boolean" } }, "required": [ "ids" ], "additionalProperties": false }, "mail_move_flag_output": { "type": "object", "properties": { "changed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "moved": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "new_id": { "type": "string" } }, "required": [ "id", "new_id" ], "additionalProperties": false } }, "not_found": { "type": "array", "items": { "type": "string" } } }, "required": [ "changed" ], "additionalProperties": false }, "mail_archive_input": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 358 }, "description": "Message `id`s to archive." } }, "required": [ "ids" ], "additionalProperties": false }, "mail_archive_output": { "type": "object", "properties": { "moved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "folder": { "type": "string" }, "ids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "new_id": { "type": "string" } }, "required": [ "id", "new_id" ], "additionalProperties": false } }, "already_there": { "type": "array", "items": { "type": "string" } }, "not_found": { "type": "array", "items": { "type": "string" } } }, "required": [ "moved", "folder" ], "additionalProperties": false }, "mail_delete_input": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 358 }, "description": "Message `id`s to delete." } }, "required": [ "ids" ], "additionalProperties": false }, "mail_delete_output": { "type": "object", "properties": { "moved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "folder": { "type": "string" }, "ids": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "new_id": { "type": "string" } }, "required": [ "id", "new_id" ], "additionalProperties": false } }, "already_there": { "type": "array", "items": { "type": "string" } }, "not_found": { "type": "array", "items": { "type": "string" } } }, "required": [ "moved", "folder" ], "additionalProperties": false }, "calendar_list_events_input": { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ], "description": "Start of the range: a date (from its first moment, in UTC) or a date and time with an offset." }, "to": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ], "description": "End of the range, at most 366 days after `from`; a date means its first moment." }, "calendar_ids": { "description": "Only these calendars, by id from list_calendars; omit for all of them.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "text": { "description": "Only events whose title, location or notes contain this, ignoring case.", "type": "string", "maxLength": 200 }, "limit": { "default": 100, "description": "How many events to return at most, earliest first.", "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "from", "to" ], "additionalProperties": false }, "calendar_list_events_output": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "calendar_id": { "type": "string" }, "title": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "all_day": { "type": "boolean" }, "time_zone": { "type": "string" }, "location": { "type": "string" }, "recurring": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "tentative", "cancelled" ] }, "response": { "type": "string", "enum": [ "accepted", "declined", "tentative", "needs_action" ] } }, "required": [ "id", "calendar_id", "title", "start", "end", "all_day" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "unavailable_calendars": { "type": "array", "items": { "type": "string" } } }, "required": [ "events", "truncated" ], "additionalProperties": false }, "calendar_read_event_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 711, "description": "The `id` of an event or occurrence from list_events." } }, "required": [ "id" ], "additionalProperties": false }, "calendar_read_event_output": { "type": "object", "properties": { "id": { "type": "string" }, "calendar_id": { "type": "string" }, "title": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "all_day": { "type": "boolean" }, "time_zone": { "type": "string" }, "location": { "type": "string" }, "recurring": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "tentative", "cancelled" ] }, "response": { "type": "string", "enum": [ "accepted", "declined", "tentative", "needs_action" ] }, "notes": { "type": "string" }, "url": { "type": "string" }, "repeats": { "type": "string" }, "organizer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": false }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "response": { "type": "string", "enum": [ "accepted", "declined", "tentative", "needs_action" ] } }, "additionalProperties": false } }, "created": { "type": "string" }, "updated": { "type": "string" } }, "required": [ "id", "calendar_id", "title", "start", "end", "all_day" ], "additionalProperties": false }, "calendar_list_calendars_input": { "type": "object", "properties": {}, "additionalProperties": false }, "calendar_list_calendars_output": { "type": "object", "properties": { "calendars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "color": { "type": "string" } }, "required": [ "id", "name", "read_only" ], "additionalProperties": false } } }, "required": [ "calendars" ], "additionalProperties": false }, "calendar_find_free_time_input": { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ], "description": "Start: a date (from its first moment in `time_zone`), or a date and time, with an offset or in `time_zone`." }, "to": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ], "description": "End, at most 31 days after `from`: a date means its first moment in `time_zone`." }, "time_zone": { "type": "string", "maxLength": 64, "description": "The person’s IANA time zone: the clock the day’s hours and the answer are on." }, "day_start": { "default": "08:00", "description": "Free time starts no earlier than this each day, HH:MM in `time_zone`.", "type": "string" }, "day_end": { "default": "20:00", "description": "Free time ends no later than this each day, HH:MM; 24:00 for midnight.", "type": "string" }, "min_minutes": { "default": 30, "description": "Only gaps at least this long, in minutes.", "type": "integer", "minimum": 5, "maximum": 720 }, "calendar_ids": { "description": "Only events in these calendars count, by id from list_calendars; omit for all.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "limit": { "default": 50, "description": "How many free spans to return at most, earliest first.", "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "from", "to", "time_zone" ], "additionalProperties": false }, "calendar_find_free_time_output": { "type": "object", "properties": { "time_zone": { "type": "string" }, "free": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "start", "end", "minutes" ], "additionalProperties": false } }, "busy_events": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "unavailable_calendars": { "type": "array", "items": { "type": "string" } } }, "required": [ "time_zone", "free", "busy_events", "truncated" ], "additionalProperties": false }, "calendar_create_event_input": { "type": "object", "properties": { "calendar_id": { "description": "Calendar id from list_calendars; omit for the first one that can be written to.", "type": "string", "maxLength": 200 }, "title": { "type": "string", "maxLength": 500, "description": "What the event is called." }, "start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ], "description": "A date for an all-day event, or a date and time, with an offset or local to `time_zone`." }, "end": { "description": "Same kind as `start`: the last day of an all-day event, or the end time; omit for one hour, or one day.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ] }, "time_zone": { "description": "IANA zone, e.g. `Europe/London`, that times without an offset are in.", "type": "string", "maxLength": 64 }, "location": { "description": "Where it happens, as one line.", "type": "string", "maxLength": 500 }, "notes": { "description": "Notes shown with the event.", "type": "string", "maxLength": 20000 }, "url": { "description": "A link to go with it.", "type": "string", "maxLength": 2000, "format": "uri" } }, "required": [ "title", "start" ], "additionalProperties": false }, "calendar_create_event_output": { "type": "object", "properties": { "id": { "type": "string" }, "calendar_id": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "all_day": { "type": "boolean" }, "time_zone": { "type": "string" } }, "required": [ "id", "calendar_id", "start", "end", "all_day" ], "additionalProperties": false }, "calendar_update_event_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 711, "description": "The `id` from list_events: an occurrence of a repeating event changes that occurrence only." }, "whole_series": { "default": false, "description": "For an occurrence: change title, location and notes of every occurrence instead; times of a series cannot change.", "type": "boolean" }, "title": { "description": "The new title.", "type": "string", "maxLength": 500 }, "start": { "description": "New start: a date for all-day, or a date and time with an offset or in `time_zone`.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ] }, "end": { "description": "New end, the same kind as `start`.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string" } ] }, "time_zone": { "description": "IANA zone that new times without an offset are in.", "type": "string", "maxLength": 64 }, "location": { "description": "New location; null removes it.", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "notes": { "description": "New notes; null removes them.", "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "calendar_update_event_output": { "type": "object", "properties": { "id": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "all_day": { "type": "boolean" }, "time_zone": { "type": "string" } }, "required": [ "id", "start", "end", "all_day" ], "additionalProperties": false }, "calendar_delete_event_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 711, "description": "The `id` from list_events: an occurrence of a repeating event deletes that occurrence only." }, "whole_series": { "default": false, "description": "For an occurrence: delete every occurrence of the series instead.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "calendar_delete_event_output": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "string", "enum": [ "event", "occurrence", "series" ] } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "contacts_search_input": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200, "description": "Part of a name, email address, phone number or organization, ignoring case." }, "address_book_id": { "description": "Only this address book, by id from list_address_books; omit for all.", "type": "string", "maxLength": 200 }, "limit": { "default": 25, "description": "How many contacts to return.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "query" ], "additionalProperties": false }, "contacts_search_output": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "address_book_id": { "type": "string" }, "name": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "phones": { "type": "array", "items": { "type": "string" } }, "organization": { "type": "string" } }, "required": [ "id", "address_book_id", "name", "emails", "phones" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "contacts", "truncated" ], "additionalProperties": false }, "contacts_read_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 711, "description": "The `id` of a contact from search." } }, "required": [ "id" ], "additionalProperties": false }, "contacts_read_output": { "type": "object", "properties": { "id": { "type": "string" }, "address_book_id": { "type": "string" }, "name": { "type": "string" }, "given_name": { "type": "string" }, "family_name": { "type": "string" }, "nickname": { "type": "string" }, "organization": { "type": "string" }, "job_title": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "label": { "type": "string" } }, "required": [ "address" ], "additionalProperties": false }, "description": "The preferred one first." }, "phones": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "label": { "type": "string" } }, "required": [ "number" ], "additionalProperties": false }, "description": "The preferred one first." }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "urls": { "type": "array", "items": { "type": "string" } }, "birthday": { "description": "YYYY-MM-DD, or --MM-DD when the year is not kept.", "type": "string" }, "notes": { "type": "string" } }, "required": [ "id", "address_book_id", "name", "emails", "phones", "addresses", "urls" ], "additionalProperties": false }, "contacts_list_address_books_input": { "type": "object", "properties": {}, "additionalProperties": false }, "contacts_list_address_books_output": { "type": "object", "properties": { "address_books": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" } }, "required": [ "id", "name", "read_only" ], "additionalProperties": false } } }, "required": [ "address_books" ], "additionalProperties": false }, "contacts_create_input": { "type": "object", "properties": { "address_book_id": { "description": "Address book id from list_address_books; omit for the first that can be written.", "type": "string", "maxLength": 200 }, "name": { "description": "The name as shown; omit to build it from the parts.", "type": "string", "maxLength": 200 }, "given_name": { "description": "First name.", "type": "string", "maxLength": 200 }, "family_name": { "description": "Last name.", "type": "string", "maxLength": 200 }, "organization": { "description": "Company or organization.", "type": "string", "maxLength": 200 }, "job_title": { "description": "Job title.", "type": "string", "maxLength": 200 }, "emails": { "description": "Email addresses, the preferred one first.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 254, "description": "The email address." }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "required": [ "address" ], "additionalProperties": false } }, "phones": { "description": "Phone numbers, the preferred one first.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "maxLength": 40, "description": "The number, as it should be dialled or shown." }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "required": [ "number" ], "additionalProperties": false } }, "addresses": { "description": "Postal addresses.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "street": { "description": "Street and number, as one line.", "type": "string", "maxLength": 200 }, "city": { "description": "Town or city.", "type": "string", "maxLength": 100 }, "region": { "description": "State, county or province.", "type": "string", "maxLength": 100 }, "postal_code": { "description": "Postal code.", "type": "string", "maxLength": 20 }, "country": { "description": "Country.", "type": "string", "maxLength": 100 }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "additionalProperties": false } }, "urls": { "description": "Web addresses.", "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 2000, "format": "uri" } }, "birthday": { "description": "Birthday as YYYY-MM-DD.", "type": "string", "format": "date" }, "notes": { "description": "Notes kept with the contact.", "type": "string", "maxLength": 20000 } }, "additionalProperties": false }, "contacts_create_output": { "type": "object", "properties": { "id": { "type": "string" }, "address_book_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "address_book_id", "name" ], "additionalProperties": false }, "contacts_update_input": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 711, "description": "The `id` of a contact from search." }, "name": { "description": "The name as shown.", "type": "string", "maxLength": 200 }, "given_name": { "description": "First name; null removes it.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "family_name": { "description": "Last name; null removes it.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "organization": { "description": "Organization; null removes it.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "job_title": { "description": "Job title; null removes it.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "emails": { "description": "Every email address it should have, the preferred one first: the list replaces the old one; [] removes all.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 254, "description": "The email address." }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "required": [ "address" ], "additionalProperties": false } }, "phones": { "description": "Every phone number it should have, the preferred one first: the list replaces the old one; [] removes all.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "maxLength": 40, "description": "The number, as it should be dialled or shown." }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "required": [ "number" ], "additionalProperties": false } }, "addresses": { "description": "Every postal address it should have, replacing the old ones; [] removes all.", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "street": { "description": "Street and number, as one line.", "type": "string", "maxLength": 200 }, "city": { "description": "Town or city.", "type": "string", "maxLength": 100 }, "region": { "description": "State, county or province.", "type": "string", "maxLength": 100 }, "postal_code": { "description": "Postal code.", "type": "string", "maxLength": 20 }, "country": { "description": "Country.", "type": "string", "maxLength": 100 }, "label": { "description": "What kind: work, home, mobile, or a word of their own.", "type": "string", "maxLength": 40 } }, "additionalProperties": false } }, "urls": { "description": "Every web address it should have, replacing the old ones; [] removes all.", "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 2000, "format": "uri" } }, "birthday": { "description": "Birthday as YYYY-MM-DD; null removes it.", "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "notes": { "description": "Notes; null removes them.", "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "contacts_update_output": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "webhook_read_input": { "type": "object", "properties": { "id": { "type": "string", "description": "The `id` of a `webhook.received` event from events.poll." } }, "required": [ "id" ], "additionalProperties": false }, "webhook_read_output": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "query": { "type": "string" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "content_type": { "type": "string" }, "event": { "type": "string" }, "body": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "verified": { "type": "boolean" } }, "required": [ "id", "at", "headers", "body", "encoding", "bytes", "verified" ], "additionalProperties": false }, "events_poll_input": { "type": "object", "properties": { "limit": { "default": 20, "description": "How many events to return.", "type": "integer", "minimum": 1, "maximum": 50 } }, "additionalProperties": false }, "events_poll_output": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "instance": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "const": "mail.received" }, "message": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "maxItems": 3, "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "flagged": { "type": "boolean" }, "has_attachments": { "type": "boolean" } }, "required": [ "id", "date", "from", "to", "subject", "unread", "flagged", "has_attachments" ], "additionalProperties": false } }, "required": [ "id", "instance", "at", "type", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "instance": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "const": "webhook.received" }, "delivery": { "type": "object", "properties": { "event": { "type": "string" }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preview": { "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "bytes", "preview", "verified" ], "additionalProperties": false } }, "required": [ "id", "instance", "at", "type", "delivery" ], "additionalProperties": false } ] } }, "more": { "type": "boolean" } }, "required": [ "events", "more" ], "additionalProperties": false }, "events_ack_input": { "type": "object", "properties": { "event_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Event `id`s that were handled." } }, "required": [ "event_ids" ], "additionalProperties": false }, "events_ack_output": { "type": "object", "properties": { "acknowledged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "acknowledged" ], "additionalProperties": false }, "brief_get_input": { "type": "object", "properties": { "date": { "description": "The day to brief, as YYYY-MM-DD in `time_zone`; omit for today.", "type": "string", "format": "date" }, "time_zone": { "description": "The person’s IANA time zone; omit for the one they set.", "type": "string", "maxLength": 64 }, "since": { "description": "Mail and deliveries from this time on, with Z or an offset; omit for the look-back the person set.", "format": "date-time", "type": "string" }, "connectors": { "description": "Only these connectors, by tool prefix such as icloud_mail; omit for those in the brief.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 32 } } }, "additionalProperties": false }, "brief_get_output": { "type": "object", "properties": { "date": { "type": "string" }, "through": { "type": "string" }, "time_zone": { "type": "string" }, "since": { "type": "string", "format": "date-time" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "connector": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "end": { "type": "string" }, "title": { "type": "string" }, "from": { "type": "string" }, "where": { "type": "string" }, "calendar": { "type": "string" }, "preview": { "type": "string" }, "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "flags": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "at", "title" ], "additionalProperties": false } }, "more": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "note": { "type": "string" } }, "required": [ "connector", "name", "kind", "items", "more" ], "additionalProperties": false } } }, "required": [ "date", "through", "time_zone", "since", "sections" ], "additionalProperties": false }, "dates_list_input": { "type": "object", "properties": { "limit": { "default": 50, "description": "At most this many dates, earliest first.", "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "dates_list_output": { "type": "object", "properties": { "time_zone": { "type": "string" }, "dates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "calendar": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string" }, "date": { "type": "string" }, "start": { "type": "string" }, "end_date": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "string" }, "status": { "type": "string" }, "from": { "type": "string" }, "source": { "type": "object", "properties": { "connector": { "type": "string" }, "message_id": { "type": "string" } }, "required": [ "connector", "message_id" ], "additionalProperties": false }, "added_at": { "type": "string", "format": "date-time" }, "changed_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "calendar", "title", "kind", "date", "status", "from", "added_at" ], "additionalProperties": false } }, "more": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "time_zone", "dates", "more" ], "additionalProperties": false } }, "responses": { "error_401": { "description": "`unauthorized`, `token_revoked`, `token_expired`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_403": { "description": "`forbidden`, `recipient_not_allowed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_404": { "description": "`not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_409": { "description": "`reconnect_required`, `changed_since_read`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_413": { "description": "`too_large`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_422": { "description": "`invalid_arguments`, `unreadable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_429": { "description": "`rate_limited`, `send_cap_reached`, `send_cooldown`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_500": { "description": "`internal`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "error_502": { "description": "`upstream_unavailable`, `upstream_rejected`, `delivery_unconfirmed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }