{
  "openapi": "3.1.0",
  "info": {
    "title": "Balsio Integrations API",
    "version": "v1",
    "x-changelog-url": "https://docs.balsio.com/changelog.html",
    "x-deprecation-policy-url": "https://docs.balsio.com/changelog.html#deprecation-policy",
    "description": "Public OpenAPI document for the Balsio integrations REST API.\n\nCreate an integration:\n- In Balsio, open the account menu and choose Integrations, or open the [Integrations page](https://balsio.com/app/integrations).\n- After creating it, use the generated token with this API or the Balsio MCP server.\n\nAuthentication:\n- Use `Authorization: Bearer sk_...` for every request.\n\nVersioning:\n- Send the `X-Minor-Version` header with the current version on every request. Breaking changes ship behind a new version; non-breaking changes apply to every version.\n- REST requests and events WebSocket upgrades without `X-Minor-Version` are deprecated and will be rejected with `400` from 2027-01-10.\n- See the [changelog](https://docs.balsio.com/changelog.html) for every version and the deprecation policy.\n\nReliability:\n- Use the `Idempotency-Key` request header to deduplicate requests.\n- REST API requests are limited to 500 per minute per integration user by default. This limit is shared across endpoints and not yet operation-specific. Higher limits are available on request — contact us if your integration needs more throughput.\n\nErrors:\n- All error responses use a consistent error envelope schema.\n- Inspect both HTTP status and `error.code` for handling logic.\n- Examples of currently documented machine-readable error codes include:\n  `forbidden`, `invalid_channel_id`, `invalid_json`, `invalid_message`,\n  `invalid_message_id`, `invalid_params`, `invalid_thread_id`, `missing_message`, `missing_thread_id`,\n  `not_authenticated`, `not_found`, and `permission_denied`.\n\nWebhooks:\n- Webhook events are signed using `x-balsio-signature`. The deprecated `x-birdy-signature` carries the same value and stops being sent after 2027-01-10.\n- Verify signatures before processing payloads.\n\nAI tools:\n- For an LLM-friendly summary, see https://docs.balsio.com/llms.txt.\n- For the canonical contract, use https://docs.balsio.com/openapi.json or https://docs.balsio.com/openapi.yaml.\n"
  },
  "servers": [
    {
      "url": "https://balsio.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Threads",
      "description": "Thread resources and related operations."
    },
    {
      "name": "Messages",
      "description": "Message resources and related operations.\n\nWhatsApp interoperability messages are not available through this API.\nThey are stored only on the user's mobile device (iPhone or Android,\none device per user) and never reach Balsio servers, so they are never\nreturned by these endpoints and never appear in events or webhooks.\n"
    },
    {
      "name": "Channels",
      "description": "Channel resources and related operations."
    },
    {
      "name": "Attachments",
      "description": "Attachment resources and related operations."
    },
    {
      "name": "Users",
      "description": "User resources and related operations."
    },
    {
      "name": "Scheduled Messages",
      "description": "Scheduled message resources and related operations."
    },
    {
      "name": "Events",
      "description": "Canonical events stream resources."
    },
    {
      "name": "Webhooks",
      "description": "Outbound webhook events for integrations."
    },
    {
      "name": "Integrations",
      "description": "Manage integrations (personal tokens and bots) created by the user."
    }
  ],
  "paths": {
    "/threads": {
      "get": {
        "tags": [
          "Threads"
        ],
        "operationId": "listThreads",
        "summary": "List threads",
        "description": "Lists threads from the authenticated integration bot inbox by default.\nResults are ordered by `last_message_created_at` (descending). For empty threads,\n`last_message_created_at` matches the thread creation timestamp.\n\n**Browsing a workspace** (`channel_id` is a workspace channel): lists that\nworkspace's threads, including public ones the caller never joined — this is how\nan integration finds a thread to join. Private threads appear only to their\nparticipants.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/threads?limit=20\" \\\n  -H \"Authorization: Bearer sk_...\"\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    \"https://balsio.com/api/v1/threads\",\n    headers={\"Authorization\": \"Bearer sk_...\"},\n    params={\"limit\": 20},\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/threads?limit=20\", {\n  headers: { Authorization: \"Bearer sk_...\" }\n});\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelId"
          },
          {
            "$ref": "#/components/parameters/ParentThreadId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/BeforeId"
          },
          {
            "$ref": "#/components/parameters/ParticipantIds"
          },
          {
            "$ref": "#/components/parameters/OneOnOneWith"
          }
        ],
        "responses": {
          "200": {
            "description": "Thread list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadListResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Threads in inbox/channel",
                    "value": {
                      "data": [
                        {
                          "id": "th_fmn8SsKHoavown2s",
                          "object": "thread",
                          "name": "Customer onboarding",
                          "description": null,
                          "last_message_excerpt": "Initial import message",
                          "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                          "last_author_ids": [
                            "u_tgJfNUiC1nDV4"
                          ],
                          "last_message_created_at": "2026-02-18T10:03:57.277962Z",
                          "user_ids": [
                            "u_tgJfNUiC1nDV4",
                            "u_zLqW4mDNJBHc2"
                          ],
                          "users": [
                            {
                              "user_id": "u_tgJfNUiC1nDV4",
                              "roles": [
                                "creator",
                                "owner"
                              ]
                            },
                            {
                              "user_id": "u_zLqW4mDNJBHc2",
                              "roles": []
                            }
                          ],
                          "users_count": 2,
                          "read_receipts": {
                            "u_tgJfNUiC1nDV4": {
                              "message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                              "read_at": "2026-02-18T10:03:57.277962Z"
                            }
                          },
                          "settings": {
                            "is_sharing_enabled": false
                          },
                          "share_link": null,
                          "parent_thread_id": null,
                          "parent_message_id": null,
                          "created_at": "2026-02-18T10:03:57.277962Z",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        },
                        {
                          "id": "th_pK3xHwR8nLb2vYqA",
                          "object": "thread",
                          "name": "One-on-one",
                          "description": null,
                          "one_on_one_user_id_pair": "u_tgJfNUiC1nDV4,u_zLqW4mDNJBHc2",
                          "last_message_excerpt": "Thanks Alice. Can you share the URL and a screenshot?",
                          "last_message_id": "m_032Kw5BC3EWyjHk83UydbF",
                          "last_author_ids": [
                            "u_zLqW4mDNJBHc2"
                          ],
                          "last_message_created_at": "2026-02-18T10:04:15.277962Z",
                          "user_ids": [
                            "u_tgJfNUiC1nDV4",
                            "u_zLqW4mDNJBHc2"
                          ],
                          "users": [
                            {
                              "user_id": "u_tgJfNUiC1nDV4",
                              "roles": [
                                "creator",
                                "owner"
                              ]
                            },
                            {
                              "user_id": "u_zLqW4mDNJBHc2",
                              "roles": []
                            }
                          ],
                          "users_count": 2,
                          "read_receipts": {
                            "u_tgJfNUiC1nDV4": {
                              "message_id": "m_032Kw5BC3EWyjHk83UydbF",
                              "read_at": "2026-02-18T10:04:15.277962Z"
                            }
                          },
                          "settings": {
                            "is_sharing_enabled": false
                          },
                          "share_link": null,
                          "parent_thread_id": null,
                          "parent_message_id": null,
                          "created_at": "2026-02-18T10:03:57.277962Z",
                          "updated_at": "2026-02-18T10:04:15.277962Z"
                        }
                      ],
                      "object": "list",
                      "has_more": false,
                      "next_cursor": null,
                      "prev_cursor": null
                    }
                  },
                  "subThreads": {
                    "summary": "Sub-threads of a parent thread",
                    "value": {
                      "data": [
                        {
                          "id": "th_9xKpQ3mRvNwT2hYs",
                          "object": "thread",
                          "name": "Check out https://example.com/page",
                          "description": null,
                          "last_message_excerpt": "Replying in a sub-thread",
                          "last_message_id": "m_7nWx5KpR2mTvQhYs",
                          "last_author_ids": [
                            "u_tgJfNUiC1nDV4"
                          ],
                          "last_message_created_at": "2026-02-18T10:05:00.000000Z",
                          "user_ids": [],
                          "users": [],
                          "users_count": 0,
                          "read_receipts": {
                            "u_tgJfNUiC1nDV4": {
                              "message_id": "m_7nWx5KpR2mTvQhYs",
                              "read_at": "2026-02-18T10:05:01.000000Z"
                            }
                          },
                          "settings": {
                            "is_sharing_enabled": false
                          },
                          "share_link": null,
                          "parent_thread_id": "th_fmn8SsKHoavown2s",
                          "parent_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                          "joined": true,
                          "created_at": "2026-02-18T10:05:00.000000Z",
                          "updated_at": "2026-02-18T10:05:00.000000Z"
                        }
                      ],
                      "object": "list",
                      "has_more": false,
                      "next_cursor": null,
                      "prev_cursor": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "createThread",
        "summary": "Create thread",
        "description": "Creates a thread and posts the first message.\n\n**Regular thread:** supply `recipient_emails` (and optionally `thread.name`\nand, for group threads, `thread.settings`).\nIf a recipient email does not yet exist, the flow may create/invite that user.\n\n**Workspace thread:** pass a workspace `channel_id` — the only way to create one.\n`thread.name` is required, because a workspace holds group threads only, so the\none-on-one form below is rejected there. `recipient_emails` chooses the participants\nand `thread.workspace_visibility` chooses whether the rest of the workspace can\nbrowse it.\n\n**One-on-one thread (DM):** supply exactly one `recipient_emails` entry and omit\n`thread.name`. If a one-on-one thread already exists between the caller and that\nrecipient, the existing thread is returned (with any supplied message posted into it)\nrather than creating a duplicate.\n\n**Self-DM:** omit `thread.name` and pass your own email as the single `recipient_emails`\nentry. The same deduplication rule applies.\n\n**Sub-thread:** supply `parent_thread_id` and `parent_message_id` instead of\n`recipient_emails`. The sub-thread is created off the given parent message.\n\nUse the `Idempotency-Key` request header to deduplicate requests.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/threads\" \\\n  -H \"Authorization: Bearer sk_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"recipient_emails\": [\"alice.finch@example.com\"],\n    \"thread\": { \"name\": \"Customer onboarding\" },\n    \"message\": { \"body\": \"Initial sync from external system\" }\n  }'\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"recipient_emails\": [\"alice.finch@example.com\"],\n    \"thread\": {\"name\": \"Customer onboarding\"},\n    \"message\": {\"body\": \"Initial sync from external system\"},\n}\n\nresponse = requests.post(\n    \"https://balsio.com/api/v1/threads\",\n    headers={\n        \"Authorization\": \"Bearer sk_...\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=payload,\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/threads\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer sk_...\",\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    recipient_emails: [\"alice.finch@example.com\"],\n    thread: { name: \"Customer onboarding\" },\n    message: { body: \"Initial sync from external system\" },\n  }),\n});\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadCreateRequest"
              },
              "examples": {
                "default": {
                  "summary": "Create a regular thread",
                  "value": {
                    "recipient_emails": [
                      "alice.finch@example.com"
                    ],
                    "thread": {
                      "name": "Customer onboarding"
                    },
                    "message": {
                      "body": "Initial sync from external system"
                    }
                  }
                },
                "oneOnOne": {
                  "summary": "Create a one-on-one thread",
                  "value": {
                    "recipient_emails": [
                      "alice.finch@example.com"
                    ],
                    "thread": {},
                    "message": {
                      "body": "Thanks Alice. Can you share the URL and a screenshot? I'll also check our auth logs on this end."
                    }
                  }
                },
                "selfDm": {
                  "summary": "Create a self-DM (one-on-one thread with yourself)",
                  "value": {
                    "recipient_emails": [
                      "alice.finch@example.com"
                    ],
                    "thread": {},
                    "message": {
                      "body": "Note to self: check auth logs tomorrow."
                    }
                  }
                },
                "subThread": {
                  "summary": "Create a sub-thread off a parent message",
                  "value": {
                    "parent_thread_id": "th_fmn8SsKHoavown2s",
                    "parent_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                    "message": {
                      "body": "Replying in a sub-thread"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Thread and first message were created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadCreateResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Regular thread created",
                    "value": {
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Initial sync from external system",
                        "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "last_author_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "last_message_created_at": "2026-02-18T10:03:58.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "read_receipts": {
                          "u_tgJfNUiC1nDV4": {
                            "message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                            "read_at": "2026-02-18T10:03:57.277962Z"
                          }
                        },
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "share_link": null,
                        "parent_thread_id": null,
                        "parent_message_id": null,
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:03:57.277962Z",
                        "idempotency_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
                      },
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "body": "Initial sync from external system",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:03:58.277962Z"
                      },
                      "thread_in_channels": [
                        {
                          "channel_id": "ch_DNb4kFmRhJp9wT",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "present",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        }
                      ]
                    }
                  },
                  "subThread": {
                    "summary": "Sub-thread created",
                    "value": {
                      "thread": {
                        "id": "th_9xKpQ3mRvNwT2hYs",
                        "object": "thread",
                        "name": "Check out https://example.com/page",
                        "description": null,
                        "last_message_excerpt": "Replying in a sub-thread",
                        "last_message_id": "m_7nWx5KpR2mTvQhYs",
                        "last_author_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "last_message_created_at": "2026-02-18T10:05:00.000000Z",
                        "user_ids": [],
                        "users": [],
                        "users_count": 0,
                        "read_receipts": {},
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "share_link": null,
                        "parent_thread_id": "th_fmn8SsKHoavown2s",
                        "parent_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "joined": true,
                        "created_at": "2026-02-18T10:05:00.000000Z",
                        "updated_at": "2026-02-18T10:05:00.000000Z"
                      },
                      "message": {
                        "id": "m_7nWx5KpR2mTvQhYs",
                        "object": "message",
                        "thread_id": "th_9xKpQ3mRvNwT2hYs",
                        "body": "Replying in a sub-thread",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:05:00.000000Z"
                      },
                      "parent_message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "body": "Follow-up from external system",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": "th_9xKpQ3mRvNwT2hYs",
                        "created_at": "2026-02-18T10:03:58.277962Z",
                        "updated_at": "2026-02-18T10:05:00.000000Z"
                      },
                      "threads_in_channels": [
                        {
                          "channel_id": "ch_DNb4kFmRhJp9wT",
                          "thread_id": "th_9xKpQ3mRvNwT2hYs",
                          "status": "present",
                          "updated_at": "2026-02-18T10:05:00.000000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "A sub-thread already exists for this parent message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "subThreadExists": {
                    "value": {
                      "error": {
                        "type": "conflict",
                        "code": "sub_thread_already_exists",
                        "message": "Can't create sub-thread",
                        "description": "A sub-thread already exists for this message",
                        "thread_id": "th_9xKpQ3mRvNwT2hYs"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/archive": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "archiveThreads",
        "summary": "Archive threads",
        "description": "Archives one or more threads for the current user.\nMoves chats from Inbox or Snoozed to Done. Archiving a snoozed chat cancels its scheduled wake-up.\nSkipped chats include current Inbox, Done and Snoozed placements in the response.\n`last_message_ids` must include one entry per `thread_id`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadArchiveRequest"
              },
              "examples": {
                "archiveMany": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "last_message_ids": [
                      {
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                      }
                    ],
                    "archived_at": "2026-02-18T10:03:57.277962Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threads were archived.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadArchiveResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread_ids": [
                        "th_fmn8SsKHoavown2s"
                      ],
                      "thread_in_channels": [
                        {
                          "channel_id": "ch_7sUNVzywAU8CGi",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "present",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        },
                        {
                          "channel_id": "ch_DNb4kFmRhJp9wT",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "absent",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/snooze": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "snoozeThreads",
        "summary": "Snooze threads",
        "description": "Snoozes one or more threads until the provided datetime.\n`last_message_ids` must include one entry per `thread_id`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadSnoozeRequest"
              },
              "examples": {
                "snoozeMany": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "snoozed_until": "2026-02-18T10:05:10.277962Z",
                    "last_message_ids": [
                      {
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                      }
                    ],
                    "snoozed_at": "2026-02-18T10:03:57.277962Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threads were snoozed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadSnoozeResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "snoozed_thread_ids": [
                        "th_fmn8SsKHoavown2s"
                      ],
                      "thread_in_channels": [
                        {
                          "channel_id": "ch_DNb4kFmRhJp9wT",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "present",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        },
                        {
                          "channel_id": "ch_7sUNVzywAU8CGi",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "absent",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/mute": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "muteThreads",
        "summary": "Mute or unmute threads",
        "description": "Mutes or unmutes one or more threads.\nSet `muted_until` to a datetime, `\"forever\"`, or `null` (to unmute).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadMuteRequest"
              },
              "examples": {
                "muteUntil": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "muted_until": "2026-02-18T11:14:33.277962Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threads were muted/unmuted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadMuteResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread_ids": [
                        "th_fmn8SsKHoavown2s"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/move": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "moveThreads",
        "summary": "Move threads between channels",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadMoveRequest"
              },
              "examples": {
                "moveMany": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "from_channel_id": "ch_DNb4kFmRhJp9wT",
                    "to_channel_id": "ch_7sUNVzywAU8CGi",
                    "moved_at": "2026-02-18T10:03:57.277962Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threads were moved.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadMoveResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread_ids": [
                        "th_fmn8SsKHoavown2s"
                      ],
                      "thread_in_channels": [
                        {
                          "channel_id": "ch_7sUNVzywAU8CGi",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "present",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        },
                        {
                          "channel_id": "ch_DNb4kFmRhJp9wT",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "status": "absent",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/share/{share_key}": {
      "get": {
        "tags": [
          "Threads"
        ],
        "operationId": "getThreadShare",
        "summary": "Retrieve thread share-link preview",
        "description": "Resolves a thread share link to a preview of the thread behind it, so a\nprospective member can see what they would be joining. Carries no roster and\nno messages.\n\nReturns `404` when the key is unknown or the thread's sharing has been turned off.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShareKeyPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Thread preview.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadPreview"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/threads/{thread_id}": {
      "get": {
        "tags": [
          "Threads"
        ],
        "operationId": "getThread",
        "summary": "Retrieve thread",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "responses": {
          "200": {
            "description": "Thread object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "th_fmn8SsKHoavown2s",
                      "object": "thread",
                      "name": "Customer onboarding",
                      "description": null,
                      "last_message_excerpt": "Initial sync from external system",
                      "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                      "last_author_ids": [
                        "u_tgJfNUiC1nDV4"
                      ],
                      "last_message_created_at": "2026-02-18T10:03:58.277962Z",
                      "user_ids": [
                        "u_tgJfNUiC1nDV4",
                        "u_zLqW4mDNJBHc2"
                      ],
                      "users": [
                        {
                          "user_id": "u_tgJfNUiC1nDV4",
                          "roles": [
                            "creator",
                            "owner"
                          ]
                        },
                        {
                          "user_id": "u_zLqW4mDNJBHc2",
                          "roles": []
                        }
                      ],
                      "users_count": 2,
                      "read_receipts": {
                        "u_tgJfNUiC1nDV4": {
                          "message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                          "read_at": "2026-02-18T10:03:57.277962Z"
                        }
                      },
                      "settings": {
                        "is_sharing_enabled": false
                      },
                      "share_link": null,
                      "created_at": "2026-02-18T10:03:57.277962Z",
                      "updated_at": "2026-02-18T10:03:57.277962Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Threads"
        ],
        "operationId": "updateThread",
        "summary": "Update a thread",
        "description": "Changes a group thread's name or description. Settings have their own endpoint\n(`PATCH /threads/{thread_id}/settings`).\n\nRequires the thread owner role; on a thread in a workspace, workspace admins\nqualify too. One-on-one threads and sub-threads are rejected.\n\n`workspace_visibility` is not part of this call — changing it announces or\nretracts the thread across the workspace, so it has its own endpoint\n(`POST /threads/{thread_id}/visibility`). Sending it here is ignored.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Thread was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUpdateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      },
      "delete": {
        "tags": [
          "Threads"
        ],
        "operationId": "deleteThread",
        "summary": "Delete a thread",
        "description": "Deletes a group thread for everyone, along with its messages. Group threads only —\none-on-one threads and sub-threads are rejected.\n\nRequires the thread owner role, or workspace admin on a thread in that workspace.\nIn a workspace the thread also disappears from the browse list of members who\nnever joined it.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "responses": {
          "200": {
            "description": "Thread was deleted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadDeleteResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/read": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "readThreads",
        "summary": "Mark threads as read or unread (bulk)",
        "description": "Stores read receipts for the current user in one or more threads.\n`message_ids` must include one entry per `thread_id`.\nPass `message_id: null` in an entry to mark that thread as unread.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadReadRequest"
              },
              "examples": {
                "readMany": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "message_ids": [
                      {
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                      }
                    ]
                  }
                },
                "unreadMany": {
                  "value": {
                    "thread_ids": [
                      "th_fmn8SsKHoavown2s"
                    ],
                    "message_ids": [
                      {
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "message_id": null
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read receipts were updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadReadResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "threads": [
                        {
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/mark_read": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "markThreadRead",
        "summary": "Mark thread as read (or unread)",
        "description": "Stores read receipt for the current user in the thread.\nPass `message_id: null` to mark as unread.\nRe-sending the message id already on the receipt succeeds without\nrewriting the receipt or emitting a `thread.read` event.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadMarkReadRequest"
              },
              "examples": {
                "markRead": {
                  "value": {
                    "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                  }
                },
                "markUnread": {
                  "value": {
                    "message_id": null
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read receipt was stored, or already matched the requested position.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadMarkReadResponse"
                },
                "examples": {
                  "read": {
                    "value": {
                      "thread_id": "th_fmn8SsKHoavown2s",
                      "message_id": "m_032Kw4XA2DVxiGj72TxcaE"
                    }
                  },
                  "unread": {
                    "value": {
                      "thread_id": "th_fmn8SsKHoavown2s",
                      "message_id": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/image": {
      "patch": {
        "tags": [
          "Threads"
        ],
        "operationId": "uploadThreadImage",
        "summary": "Set thread image",
        "description": "Sets an uploaded image on a group thread. Upload the image as\nmultipart/form-data with an `image_file` field. Returns the updated thread.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ThreadImageUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The thread with its new image.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/images/{image_id}/download": {
      "get": {
        "tags": [
          "Threads"
        ],
        "operationId": "downloadThreadImage",
        "summary": "Download thread image",
        "description": "Redirects to a signed media service URL where the decrypted thread image\ncan be downloaded. The redirect URL includes a time-limited signature.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "name": "image_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Thread image file key."
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to signed media service download URL.",
            "headers": {
              "location": {
                "description": "Signed media service URL for downloading the decrypted image.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundMessageOnly"
          }
        }
      }
    },
    "/threads/{thread_id}/settings": {
      "patch": {
        "tags": [
          "Threads"
        ],
        "operationId": "updateThreadSettings",
        "summary": "Update a thread's settings",
        "description": "Changes a group thread's settings. Only the keys present are changed.\n\nRequires the thread owner role; on a thread in a workspace, workspace admins\nqualify too. One-on-one threads and sub-threads are rejected.\n\nIn a workspace only four settings may be changed — `is_email_digests_disabled`,\n`is_participant_notifications_disabled`, `disable_participant_messaging` and\n`disable_participant_sub_thread_messaging`. Any other key is rejected, and\nsharing can't be enabled on a workspace thread at all.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadSettingsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings were updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUpdateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/visibility": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "updateThreadVisibility",
        "summary": "Change a workspace thread's visibility",
        "description": "Changes who can reach a workspace thread. `public` is browsable and joinable by\nevery workspace member; `private` is reachable only by its participants.\n\nTurning a thread private retracts it from every member who had not joined — they\nlose the thread and its messages. Turning it public announces it to the workspace,\nexactly as creating it there would.\n\nOpen to a participant who is a thread admin or a workspace admin. Membership is\nrequired even of a workspace admin, because privatising a thread revokes the\nactor's own access to it. A thread outside a workspace has no visibility to change.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadVisibilityUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Visibility was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadVisibilityUpdateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/workspace": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "moveThreadToWorkspace",
        "summary": "Move a thread into a workspace",
        "description": "Moves an existing thread into a workspace, where it becomes a workspace thread\nwith a single ownerless placement in that channel. One-directional — there is no\nmove back out, and this is distinct from `POST /threads/move`, which shuffles\nthreads between a user's own channels.\n\nRequires owning both the thread and the workspace.\n\nThe thread keeps its participants, except those who are not workspace members:\nthey are dropped unless named in `external_emails`, which keeps them as external\nparticipants of that one thread. Workspace members are not added — they gain\nbrowse access only, and only while the thread is public.\n\nMoving in forces `hide_participants` off and clears any share link, since a\nworkspace thread never hides its roster and never carries one.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadWorkspaceMoveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Thread was moved into the workspace.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadWorkspaceMoveResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/threads/{thread_id}/join": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "joinThread",
        "summary": "Join a thread",
        "description": "Joins a thread, putting it in the caller's inbox and starting notifications.\n\nSend `share_key` to join from a thread's share link — resolve the link with\n`GET /threads/share/{share_key}` first to see what it leads to. Omit it to join\na public thread in a workspace the caller belongs to, or a sub-thread they can\nalready read.\n\nA private workspace thread cannot be joined: it never appears in browse and a\njoin attempt is answered as if it did not exist. The only way in is to be added\nas a participant.\n\nSending `share_key` as an empty string is a malformed request rather than a\nmember join — omit the field entirely instead.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadJoinRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Thread was joined.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadJoinResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/threads/{thread_id}/leave": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "leaveThread",
        "summary": "Leave a thread",
        "description": "Leaves a thread, removing it from the caller's inbox.\n\nA public workspace thread stays browsable and can be rejoined. Leaving a private\none, or leaving as an external participant, severs access entirely — the only way\nback in is to be added again.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "responses": {
          "200": {
            "description": "Thread was left.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadLeaveResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/users": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "addThreadUsers",
        "summary": "Add users to thread",
        "description": "Adds users by email and returns the updated thread object.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadAddUsersRequest"
              },
              "examples": {
                "addByEmail": {
                  "value": {
                    "emails": [
                      "alice.finch@example.com"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Users were added.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUsersMutationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      },
      "delete": {
        "tags": [
          "Threads"
        ],
        "operationId": "removeThreadUsers",
        "summary": "Remove users from thread",
        "description": "Removes users by prefixed user ids and returns the updated thread object.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadRemoveUsersRequest"
              },
              "examples": {
                "removeById": {
                  "value": {
                    "user_ids": [
                      "u_zLqW4mDNJBHc2"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Users were removed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUsersMutationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/users/roles/{role}": {
      "post": {
        "tags": [
          "Threads"
        ],
        "operationId": "addThreadUserRole",
        "summary": "Add role for users in thread",
        "description": "Grants a role to the provided users in the thread.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/Role"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadRoleMutationRequest"
              },
              "examples": {
                "addOwner": {
                  "value": {
                    "user_ids": [
                      "u_zLqW4mDNJBHc2"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role was added for users.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUsersMutationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "users": [
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": [
                              "owner"
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      },
      "delete": {
        "tags": [
          "Threads"
        ],
        "operationId": "removeThreadUserRole",
        "summary": "Remove role for users in thread",
        "description": "Revokes a role from the provided users in the thread.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/Role"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadRoleMutationRequest"
              },
              "examples": {
                "removeOwner": {
                  "value": {
                    "user_ids": [
                      "u_zLqW4mDNJBHc2"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role was removed for users.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadUsersMutationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "users": [
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/messages": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "listThreadMessages",
        "summary": "List messages in thread",
        "description": "Preferred endpoint for fetching messages scoped to a thread.\nSupports pagination via `limit` and `before_id` (message cursor).\nReturns `400` when the `thread_id` is malformed.\nReturns `404` when the thread is not accessible to the authenticated integration user.\nWhatsApp interoperability messages are never included; they live only on\nthe user's mobile device and never reach Balsio servers.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages?limit=20\" \\\n  -H \"Authorization: Bearer sk_...\"\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages\",\n    headers={\"Authorization\": \"Bearer sk_...\"},\n    params={\"limit\": 20},\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\n  \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages?limit=20\",\n  { headers: { Authorization: \"Bearer sk_...\" } }\n);\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/BeforeId"
          }
        ],
        "responses": {
          "200": {
            "description": "Message list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "data": [
                        {
                          "id": "m_032Kw4XA2DVxiGj72TxcaE",
                          "object": "message",
                          "thread_id": "th_fmn8SsKHoavown2s",
                          "user_id": "u_tgJfNUiC1nDV4",
                          "body": "Follow-up from external system",
                          "reply_to_message_excerpt": null,
                          "sub_thread_id": null,
                          "created_at": "2026-02-18T10:04:15.277962Z"
                        }
                      ],
                      "object": "list",
                      "has_more": false,
                      "next_cursor": null,
                      "prev_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "createThreadMessage",
        "summary": "Create message in thread",
        "description": "Preferred endpoint for creating a message in a specific thread.\nThe authenticated integration user must be a thread participant.\nReturns `400` when the `thread_id` is malformed or when both `body` and `attachments` are missing.\n\nAlso works with sub-thread IDs — once a sub-thread is created via\n`POST /threads`, use this endpoint to post follow-up messages into it.\n\nUse the `Idempotency-Key` request header to deduplicate requests.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages\" \\\n  -H \"Authorization: Bearer sk_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: cb25dfd0-add8-4e90-81c1-1a07e3581dfa\" \\\n  -d '{\"message\": {\"body\": \"Follow-up from external system\"}}'\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\npayload = {\"message\": {\"body\": \"Follow-up from external system\"}}\n\nresponse = requests.post(\n    \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages\",\n    headers={\n        \"Authorization\": \"Bearer sk_...\",\n        \"Content-Type\": \"application/json\",\n        \"Idempotency-Key\": \"cb25dfd0-add8-4e90-81c1-1a07e3581dfa\",\n    },\n    json=payload,\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\n  \"https://balsio.com/api/v1/threads/th_fmn8SsKHoavown2s/messages\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: \"Bearer sk_...\",\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      message: { body: \"Follow-up from external system\" },\n    }),\n  }\n);\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadMessageCreateRequest"
              },
              "examples": {
                "default": {
                  "summary": "Post into a thread",
                  "value": {
                    "message": {
                      "body": "Follow-up from external system"
                    }
                  }
                },
                "subThread": {
                  "summary": "Post into a sub-thread",
                  "value": {
                    "message": {
                      "body": "Follow-up in the sub-thread"
                    }
                  }
                },
                "withAttachments": {
                  "summary": "Message with attachments",
                  "value": {
                    "message": {
                      "body": "See attached screenshot",
                      "attachments": [
                        {
                          "id": "att_DT7QcSFMRe5mlz"
                        }
                      ]
                    }
                  }
                },
                "attachmentOnly": {
                  "summary": "Attachment-only message (no body)",
                  "value": {
                    "message": {
                      "attachments": [
                        {
                          "id": "att_DT7QcSFMRe5mlz"
                        }
                      ]
                    }
                  }
                },
                "reply": {
                  "summary": "Threaded reply",
                  "value": {
                    "message": {
                      "body": "Thanks Alice. Can you share the URL and a screenshot? I'll also check our auth logs on this end.",
                      "reply_to": "m_032Kw4XA2DVxiGj72TxcaE"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message was created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageCreateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "body": "Follow-up from external system",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:04:15.277962Z",
                        "idempotency_key": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
                      },
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Follow-up from external system",
                        "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "last_author_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "last_message_created_at": "2026-02-18T10:04:15.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:05:10.277962Z"
                      }
                    }
                  },
                  "reply": {
                    "summary": "Threaded reply",
                    "value": {
                      "message": {
                        "id": "m_032Kw5BC3EWyjHk83UydbF",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_zLqW4mDNJBHc2",
                        "body": "Thanks Alice. Can you share the URL and a screenshot? I'll also check our auth logs on this end.",
                        "reply_to": "m_032Kw4XA2DVxiGj72TxcaE",
                        "reply_to_message_excerpt": "Hi — I can't log in after resetting my password. The reset link said success but I'm getting \"invalid credentials\" on every attempt.",
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:04:15.277962Z",
                        "idempotency_key": "9c1d2e7f-3b4a-4f6c-8a1e-5d8f3c7a9b1d"
                      },
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Thanks Alice. Can you share the URL and a screenshot? I'll also check our auth logs on this end.",
                        "last_message_id": "m_032Kw5BC3EWyjHk83UydbF",
                        "last_author_ids": [
                          "u_zLqW4mDNJBHc2"
                        ],
                        "last_message_created_at": "2026-02-18T10:04:15.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:05:10.277962Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/messages/{message_id}": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "getThreadMessage",
        "summary": "Retrieve message in thread",
        "description": "Preferred endpoint for retrieving a single message scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed.\nReturns `404` when the message does not belong to the provided `thread_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Message object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "m_032Kw4XA2DVxiGj72TxcaE",
                      "object": "message",
                      "thread_id": "th_fmn8SsKHoavown2s",
                      "user_id": "u_tgJfNUiC1nDV4",
                      "body": "Follow-up from external system",
                      "reply_to_message_excerpt": null,
                      "sub_thread_id": null,
                      "created_at": "2026-02-18T10:04:15.277962Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Messages"
        ],
        "operationId": "updateThreadMessage",
        "summary": "Update message in thread",
        "description": "Preferred endpoint for full message update scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed.\nReturns `404` when the message does not belong to the provided `thread_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageUpdateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "message": {
                      "body": "Updated follow-up text"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageUpdateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "body": "Updated follow-up text",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:04:15.277962Z",
                        "updated_at": "2026-02-18T10:08:24.277962Z",
                        "edited_at": "2026-02-18T10:08:24Z"
                      },
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Updated follow-up text",
                        "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "last_author_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "last_message_created_at": "2026-02-18T10:04:15.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:05:10.277962Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      },
      "patch": {
        "tags": [
          "Messages"
        ],
        "operationId": "patchThreadMessage",
        "summary": "Patch message in thread",
        "description": "Preferred endpoint for partial message update scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed or when the `message` body is missing.\nReturns `404` when the message does not belong to the provided `thread_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageUpdateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "message": {
                      "body": "Patched follow-up text"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageUpdateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "body": "Patched follow-up text",
                        "reply_to_message_excerpt": null,
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:04:15.277962Z",
                        "updated_at": "2026-02-18T10:08:24.277962Z",
                        "edited_at": "2026-02-18T10:08:24Z"
                      },
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Patched follow-up text",
                        "last_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "last_author_ids": [
                          "u_tgJfNUiC1nDV4"
                        ],
                        "last_message_created_at": "2026-02-18T10:04:15.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:05:10.277962Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      },
      "delete": {
        "tags": [
          "Messages"
        ],
        "operationId": "deleteThreadMessage",
        "summary": "Delete message in thread",
        "description": "Preferred endpoint for deleting a message scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed.\nReturns `404` when the message does not belong to the provided `thread_id`.\nThread owners can delete any message in the thread.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Message was deleted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageDeleteResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "sub_thread_id": null,
                        "created_at": "2026-02-18T10:04:15.277962Z",
                        "updated_at": "2026-02-18T11:14:33.277962Z",
                        "deleted_at": "2026-02-18T11:14:33.277962Z"
                      },
                      "message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                      "deleted_at": "2026-02-18T11:14:33.277962Z",
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "description": null,
                        "last_message_excerpt": "Initial import message",
                        "last_message_id": "m_032Kw5BC3EWyjHk83UydbF",
                        "last_author_ids": [
                          "u_zLqW4mDNJBHc2"
                        ],
                        "last_message_created_at": "2026-02-18T10:03:58.277962Z",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:03:58.277962Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/threads/{thread_id}/messages/{message_id}/reactions": {
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "addThreadMessageReaction",
        "summary": "Add reaction to message in thread",
        "description": "Preferred endpoint for adding a reaction to a message scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed.\nReturns `404` when the message does not belong to the provided `thread_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReactionCreateRequest"
              },
              "examples": {
                "thumbsUp": {
                  "value": {
                    "name": "thumbs_up"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reaction was added.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReactionAddResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/threads/{thread_id}/messages/{message_id}/reactions/{name}": {
      "delete": {
        "tags": [
          "Messages"
        ],
        "operationId": "removeThreadMessageReaction",
        "summary": "Remove reaction from message in thread",
        "description": "Preferred endpoint for removing a reaction from a message scoped to a thread.\nReturns `400` when the `thread_id` or `message_id` is malformed.\nReturns `404` when the message does not belong to the provided `thread_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadId"
          },
          {
            "$ref": "#/components/parameters/MessageId"
          },
          {
            "$ref": "#/components/parameters/ReactionName"
          }
        ],
        "responses": {
          "200": {
            "description": "Reaction was removed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReactionRemoveResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                      "thread_id": "th_fmn8SsKHoavown2s",
                      "user_id": "u_tgJfNUiC1nDV4",
                      "name": "thumbs_up"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/integrations": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "operationId": "listIntegrations",
        "summary": "List integrations",
        "description": "Lists integrations visible to the caller. A personal access token sees all integrations\nthe user has created; a bot sees only the integrations it directly created.\n",
        "responses": {
          "200": {
            "description": "Integration list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "data": [
                        {
                          "id": "int_Hs4kPq9Lm2Vx7Cd",
                          "object": "integration",
                          "name": "Acme Support Sync",
                          "status": "active",
                          "type": "personal_token",
                          "token_last_four": "f3A9",
                          "webhook_url": "https://example.com/webhooks/balsio",
                          "last_ip": "203.0.113.42",
                          "email": "alice.finch@example.com",
                          "last_used_at": "2026-02-18T10:03:57Z",
                          "created_at": "2026-02-18T10:03:57Z",
                          "updated_at": "2026-02-18T10:03:57Z"
                        }
                      ],
                      "object": "list",
                      "has_more": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Integrations"
        ],
        "operationId": "createIntegration",
        "summary": "Create integration",
        "description": "Creates an integration. A `personal_token` acts as the creator; a `bot` gets its own user.\nThe `token` (and, when a `webhook_url` is set, the `webhook_signing_secret`) are returned\nonly once in this response and cannot be retrieved later.\n\nReturns `403` when the account's active integration limit is reached or when a bot attempts\nto create a `personal_token`, and `429` when too many are created in a short period.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntegrationCreateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "integration": {
                      "name": "Acme Support Sync",
                      "type": "personal_token",
                      "webhook_url": "https://example.com/webhooks/balsio"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Integration was created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationCreateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "integration": {
                        "id": "int_Hs4kPq9Lm2Vx7Cd",
                        "object": "integration",
                        "name": "Acme Support Sync",
                        "status": "active",
                        "type": "personal_token",
                        "token_last_four": "f3A9",
                        "webhook_url": "https://example.com/webhooks/balsio",
                        "last_ip": null,
                        "email": "alice.finch@example.com",
                        "last_used_at": null,
                        "created_at": "2026-02-18T10:03:57Z",
                        "updated_at": "2026-02-18T10:03:57Z"
                      },
                      "token": "sk_...",
                      "webhook_signing_secret": "whsec_..."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/integrations/{integration_id}": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "operationId": "getIntegration",
        "summary": "Retrieve integration",
        "description": "Retrieves a single visible integration. A personal access token sees any of the user's\nintegrations; a bot sees only the integrations it directly created.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IntegrationIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Integration object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "integration": {
                        "id": "int_Hs4kPq9Lm2Vx7Cd",
                        "object": "integration",
                        "name": "Acme Support Sync",
                        "status": "active",
                        "type": "personal_token",
                        "token_last_four": "f3A9",
                        "webhook_url": "https://example.com/webhooks/balsio",
                        "last_ip": "203.0.113.42",
                        "email": "alice.finch@example.com",
                        "last_used_at": "2026-02-18T10:03:57Z",
                        "created_at": "2026-02-18T10:03:57Z",
                        "updated_at": "2026-02-18T10:03:57Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Integrations"
        ],
        "operationId": "updateIntegration",
        "summary": "Update integration",
        "description": "Updates an integration. Omitted fields are left unchanged; an empty `webhook_url` clears it.\nA `webhook_signing_secret` is returned only when setting a `webhook_url` on an integration\nthat has no signing secret yet.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IntegrationIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntegrationUpdateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "integration": {
                      "name": "Acme Support Sync",
                      "webhook_url": "https://example.com/webhooks/balsio"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Integration was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationUpdateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "integration": {
                        "id": "int_Hs4kPq9Lm2Vx7Cd",
                        "object": "integration",
                        "name": "Acme Support Sync",
                        "status": "active",
                        "type": "personal_token",
                        "token_last_four": "f3A9",
                        "webhook_url": "https://example.com/webhooks/balsio",
                        "last_ip": "203.0.113.42",
                        "email": "alice.finch@example.com",
                        "last_used_at": "2026-02-18T10:03:57Z",
                        "created_at": "2026-02-18T10:03:57Z",
                        "updated_at": "2026-02-18T10:03:57Z"
                      },
                      "webhook_signing_secret": "whsec_..."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The integration is revoked and can't be updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Integrations"
        ],
        "operationId": "revokeIntegration",
        "summary": "Revoke integration",
        "description": "Revokes the integration's token.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IntegrationIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Integration was revoked.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "integration": {
                        "id": "int_Hs4kPq9Lm2Vx7Cd",
                        "object": "integration",
                        "name": "Acme Support Sync",
                        "status": "revoked",
                        "type": "personal_token",
                        "token_last_four": "f3A9",
                        "webhook_url": "https://example.com/webhooks/balsio",
                        "last_ip": "203.0.113.42",
                        "email": "alice.finch@example.com",
                        "last_used_at": "2026-02-18T10:03:57Z",
                        "created_at": "2026-02-18T10:03:57Z",
                        "updated_at": "2026-02-18T10:03:57Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/integrations/{integration_id}/avatar": {
      "put": {
        "tags": [
          "Integrations"
        ],
        "operationId": "updateIntegrationAvatar",
        "summary": "Set integration avatar",
        "description": "Sets the avatar for a bot integration. Only bot integrations have an avatar.\nUpload the image as multipart/form-data with an `avatar_file` field.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IntegrationIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/IntegrationAvatarUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Avatar was set.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The integration is revoked and can't be updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "503": {
            "description": "Avatar storage is temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Integrations"
        ],
        "operationId": "deleteIntegrationAvatar",
        "summary": "Remove integration avatar",
        "description": "Removes the avatar from a bot integration. Only bot integrations have an avatar.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IntegrationIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Avatar was removed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The integration is revoked and can't be updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "503": {
            "description": "Avatar storage is temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/channels": {
      "get": {
        "tags": [
          "Channels"
        ],
        "operationId": "listChannels",
        "summary": "List channels",
        "description": "Lists channels visible to the authenticated integration user.\nIncludes system channels (`inbox`, `snoozed`, `archive`), personal\nchannels, and the workspaces the user is a member of.\n",
        "responses": {
          "200": {
            "description": "Channel list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "data": [
                        {
                          "id": "ch_DNb4kFmRhJp9wT",
                          "object": "channel",
                          "name": "Inbox",
                          "role": "inbox",
                          "order": 0,
                          "deleted_at": null,
                          "created_at": "2026-02-18T10:03:57.277962Z",
                          "updated_at": "2026-02-18T10:03:57.277962Z"
                        },
                        {
                          "id": "ch_7sUNVzywAU8CGi",
                          "object": "channel",
                          "name": "Customer followups",
                          "role": "personal",
                          "order": 1771409037.277962,
                          "deleted_at": null,
                          "created_at": "2026-02-18T10:03:57.277962Z",
                          "updated_at": "2026-02-18T10:03:57.277962Z",
                          "icon": {
                            "color": "blue",
                            "emoji": "📌"
                          }
                        }
                      ],
                      "object": "list",
                      "has_more": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Channels"
        ],
        "operationId": "createChannel",
        "summary": "Create channel",
        "description": "Creates a personal channel for the authenticated integration user.\n\nUse the `Idempotency-Key` request header to deduplicate requests.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChannelCreateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "channel": {
                      "name": "Customer followups",
                      "icon": {
                        "color": "blue",
                        "emoji": "📌"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Channel was created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelCreateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "channel": {
                        "id": "ch_7sUNVzywAU8CGi",
                        "object": "channel",
                        "name": "Customer followups",
                        "role": "personal",
                        "order": 1771409037.277962,
                        "deleted_at": null,
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:03:57.277962Z",
                        "icon": {
                          "color": "blue",
                          "emoji": "📌"
                        },
                        "idempotency_key": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/workspaces": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "createWorkspace",
        "summary": "Create a workspace",
        "description": "Creates a workspace — a shared space whose members browse every public thread in\nit and opt into the ones they want. The caller becomes its owner.\n\nMembers named in `member_emails` are added straight away, and an address with no\naccount yet is invited as a new user, so this reaches people outside Balsio. Send\n`[]` to start alone and add people later. Anyone who has blocked the caller is\nleft out and reported in the reply `notes`.\n\nUse the `Idempotency-Key` request header to deduplicate retries: a key that\nalready created a workspace returns that same workspace and invites nobody again.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Workspace was created, or the idempotency key matched an existing one.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "A limit was reached, or an invitee cannot be added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The workspace already exists but could not be read back; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{channel_id}": {
      "patch": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "updateWorkspace",
        "summary": "Update a workspace",
        "description": "Renames a workspace or changes its icon. Owner-only. The join link is a\nsetting, so it is toggled through `PATCH /workspaces/{channel_id}/settings`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceChannelResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/workspaces/{channel_id}/settings": {
      "patch": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "updateWorkspaceSettings",
        "summary": "Update a workspace's settings",
        "description": "Turns the workspace join link on or off. Owner-only.\n\nTurning it off clears the key, so a link already shared stops working. Turning\nit back on mints a new one.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceSettingsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings were updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceChannelResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/workspaces/{channel_id}/users": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "addWorkspaceMembers",
        "summary": "Add members to a workspace",
        "description": "Adds members by email. Owner-only. An address with no account yet is invited as a\nnew user, so this reaches people outside Balsio.\n\nA new member gains browse access to the workspace's public threads; nothing is\nadded to their inbox and existing threads are not backfilled, so the client loads\nthem with the workspace browse sync. Private threads are not included.\n\nIf a new member was an external participant on one of the workspace's threads,\nthat `external` role is cleared and they become a normal participant.\n\nAnyone who has blocked the caller is left out and reported in the reply `notes`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceMembersAddRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Members were added.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceMembersResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "The workspace is at its member limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "removeWorkspaceMembers",
        "summary": "Remove members from a workspace",
        "description": "Removes members. Owner-only, and a caller cannot remove themselves — use\n`POST /workspaces/{channel_id}/leave`.\n\nA removed member is dropped from every thread in the workspace at once, and that\nis silent: no thread posts a \"left the chat\" message, however many they were in.\nThe departure belongs to the workspace, not to its threads.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUserIdsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Members were removed.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceMembersResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/workspaces/{channel_id}/users/roles/{role}": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "addWorkspaceMemberRole",
        "summary": "Grant a workspace role",
        "description": "Grants a workspace role. Owner-only, and `owner` is the only role today.\n\nAn owner manages the workspace and every thread in it, including threads they\nhave not joined — but not private threads they are not a participant of.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceRolePath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUserIdsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role was granted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceMembersResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "removeWorkspaceMemberRole",
        "summary": "Revoke a workspace role",
        "description": "Revokes a workspace role, leaving the person a member. Owner-only, and `owner` is\nthe only role today.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceRolePath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUserIdsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role was revoked.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceMembersResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/workspaces/join": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "joinWorkspace",
        "summary": "Join a workspace by join link",
        "description": "Joins a workspace from its join link. Resolve the link with\n`GET /channels/share/{share_key}` first to see which workspace it leads to.\n\nMembership grants browse access to the workspace's public threads; it adds\nnothing to the caller's inbox. Join the threads you want with\n`POST /threads/{thread_id}/join`. Private threads are not included — joining a\nworkspace grants nothing on them.\n\nA caller who is already a member is rejected rather than silently succeeding.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceJoinRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace was joined.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceChannelResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The workspace is at its member limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{channel_id}/leave": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "operationId": "leaveWorkspace",
        "summary": "Leave a workspace",
        "description": "Leaves a workspace. The caller is dropped from every thread in it at once, and\nthat departure is silent — no thread posts a \"left the chat\" message, however\nmany the caller was in. The departure belongs to the workspace, not its threads.\n\nIf the caller is the last owner, the remaining members are promoted to owner\nfirst, so a workspace is never left without one.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace was left.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceLeaveResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/channels/share/{share_key}": {
      "get": {
        "tags": [
          "Channels"
        ],
        "operationId": "getChannelShare",
        "summary": "Retrieve workspace join-link preview",
        "description": "Resolves a workspace join link to a preview of the workspace behind it, so a\nprospective member can see what they would be joining. Carries no roster.\n\nReturns `404` when the key is unknown or the workspace has sharing turned off.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShareKeyPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace preview.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelPreview"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/channels/{channel_id}": {
      "get": {
        "tags": [
          "Channels"
        ],
        "operationId": "getChannel",
        "summary": "Retrieve channel",
        "description": "Retrieves a single visible channel by id.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Channel object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Channel"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "ch_7sUNVzywAU8CGi",
                      "object": "channel",
                      "name": "Customer followups",
                      "role": "personal",
                      "order": 1771409037.277962,
                      "deleted_at": null,
                      "created_at": "2026-02-18T10:03:57.277962Z",
                      "updated_at": "2026-02-18T10:03:57.277962Z",
                      "icon": {
                        "color": "blue",
                        "emoji": "📌"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Channels"
        ],
        "operationId": "updateChannel",
        "summary": "Update channel",
        "description": "Fully updates a mutable channel.\nSystem channels are immutable and return `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChannelUpdateRequest"
              },
              "examples": {
                "rename": {
                  "value": {
                    "channel": {
                      "name": "Customer followups urgent"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Channel was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelUpdateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "channel": {
                        "id": "ch_7sUNVzywAU8CGi",
                        "object": "channel",
                        "name": "Customer followups urgent",
                        "role": "personal",
                        "order": 1771409037.277962,
                        "deleted_at": null,
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:03:57.277962Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Channel cannot be updated because it is not mutable.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "systemChannel": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "permission_denied",
                        "message": "Can't update channel",
                        "description": "System channels cannot be updated"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Channel not found or not visible to the integration user.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "not_found",
                        "message": "Can't update channel",
                        "description": "Channel not found"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation failed for the channel payload.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidOrder": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "invalid_params",
                        "message": "Can't update channel",
                        "description": "Order must be greater than or equal to 0"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Channels"
        ],
        "operationId": "patchChannel",
        "summary": "Patch channel",
        "description": "Partially updates a mutable channel.\nSystem channels are immutable and return `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChannelUpdateRequest"
              },
              "examples": {
                "iconUpdate": {
                  "value": {
                    "channel": {
                      "icon": {
                        "color": "green",
                        "emoji": "✅"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Channel was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelUpdateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "channel": {
                        "id": "ch_7sUNVzywAU8CGi",
                        "object": "channel",
                        "name": "Customer followups",
                        "role": "personal",
                        "order": 1771409037.277962,
                        "deleted_at": null,
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:03:57.277962Z",
                        "icon": {
                          "color": "green",
                          "emoji": "✅"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Channel cannot be updated because it is not mutable.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "systemChannel": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "permission_denied",
                        "message": "Can't update channel",
                        "description": "System channels cannot be updated"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Channel not found or not visible to the integration user.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "not_found",
                        "message": "Can't update channel",
                        "description": "Channel not found"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation failed for the channel payload.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidOrder": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "invalid_params",
                        "message": "Can't update channel",
                        "description": "Order must be greater than or equal to 0"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Channels"
        ],
        "operationId": "deleteChannel",
        "summary": "Delete channel",
        "description": "Soft-deletes a personal channel.\nSystem channels cannot be deleted and return `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Channel was deleted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChannelDeleteResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "channel_id": "ch_7sUNVzywAU8CGi",
                      "deleted_at": "2026-02-18T10:03:57.277962Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Delete is forbidden for system channels.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "systemChannelForbidden": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "forbidden",
                        "message": "Can't delete channel",
                        "description": "Cannot delete system channels"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Channel not found or not visible to the integration user.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "not_found",
                        "message": "Can't delete channel",
                        "description": "Channel not found"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid channel id payload.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidChannelId": {
                    "value": {
                      "error": {
                        "type": "bad_request",
                        "code": "invalid_channel_id",
                        "message": "Can't delete channel",
                        "description": "Invalid channel ID format"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/channels/{channel_id}/image": {
      "patch": {
        "tags": [
          "Channels"
        ],
        "operationId": "uploadChannelImage",
        "summary": "Set channel image",
        "description": "Sets an uploaded image on a personal or workspace channel. Upload the\nimage as multipart/form-data with an `image_file` field.\n\nA channel shows **either** an uploaded image **or** a `{ color, emoji }`\nicon — they are mutually exclusive. Setting an image here clears the icon;\nto remove the image (and go back to an icon), set the icon via\n`PATCH /channels/{channel_id}`, which clears the image.\n\nWorkspace channels require the caller to be an owner; system channels are immutable.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ChannelImageUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The channel with its new image.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Channel"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          }
        }
      }
    },
    "/channels/{channel_id}/images/{image_id}/download": {
      "get": {
        "tags": [
          "Channels"
        ],
        "operationId": "downloadChannelImage",
        "summary": "Download channel image",
        "description": "Redirects to a signed media service URL where the decrypted channel image\ncan be downloaded. The redirect URL includes a time-limited signature.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ChannelIdPath"
          },
          {
            "name": "image_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Channel image file key."
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to signed media service download URL.",
            "headers": {
              "location": {
                "description": "Signed media service URL for downloading the decrypted image.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/attachments": {
      "post": {
        "tags": [
          "Attachments"
        ],
        "operationId": "createAttachment",
        "summary": "Create attachment metadata",
        "description": "Creates attachment metadata and returns a signed upload URL.\nThis endpoint does not upload file bytes.\nUpload the file (max 10 MB) by POSTing to the signed `attachment.upload_url`\nas multipart/form-data with a `file` field.\n\nAfter uploading, include the attachment ID in the `attachments` array when\ncreating a message.\n\nUse the `Idempotency-Key` request header to deduplicate requests.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/attachments\" \\\n  -H \"Authorization: Bearer sk_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filename\": \"screenshot-login-error.png\",\n    \"content_type\": \"image/png\",\n    \"size\": 204800\n  }'\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"filename\": \"screenshot-login-error.png\",\n    \"content_type\": \"image/png\",\n    \"size\": 204800,\n}\n\nresponse = requests.post(\n    \"https://balsio.com/api/v1/attachments\",\n    headers={\n        \"Authorization\": \"Bearer sk_...\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=payload,\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/attachments\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer sk_...\",\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    filename: \"screenshot-login-error.png\",\n    content_type: \"application/pdf\",\n    size: 204800,\n  }),\n});\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachmentCreateRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "filename": "screenshot-login-error.png",
                    "content_type": "image/png",
                    "size": 204800
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Attachment metadata created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttachmentCreateResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "attachment": {
                        "id": "att_DT7QcSFMRe5mlz",
                        "upload_url": "https://media.balsio.com/attachments/att_DT7QcSFMRe5mlz/upload?expires=1749638400&op=upload&sig=ab12cd34...",
                        "idempotency_key": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "Attachment metadata validation failed (for example missing filename or invalid size).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidPayload": {
                    "value": {
                      "error": {
                        "message": "Can't create attachment",
                        "description": "Expected attachment metadata fields"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/attachments/{attachment_id}": {
      "get": {
        "tags": [
          "Attachments"
        ],
        "operationId": "getAttachment",
        "summary": "Retrieve attachment metadata",
        "parameters": [
          {
            "$ref": "#/components/parameters/AttachmentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Attachment"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "att_DT7QcSFMRe5mlz",
                      "object": "attachment",
                      "type": "file",
                      "filename": "screenshot-login-error.png",
                      "content_type": "image/png",
                      "key": "att_DT7QcSFMRe5mlz.enc",
                      "size": 204800,
                      "status": "pending",
                      "user_id": "u_tgJfNUiC1nDV4",
                      "thread_id": null,
                      "message_id": null,
                      "width": null,
                      "height": null,
                      "preview_size": null,
                      "preview_width": null,
                      "preview_height": null,
                      "preview_status": null,
                      "created_at": "2026-02-18T10:03:57.277962Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundMessageOnly"
          }
        }
      },
      "delete": {
        "tags": [
          "Attachments"
        ],
        "operationId": "deleteAttachment",
        "summary": "Delete attachment",
        "description": "Soft-deletes an attachment visible to the integration user.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AttachmentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment deleted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttachmentDeleteResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "attachment_id": "att_DT7QcSFMRe5mlz"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundMessageOnly"
          },
          "422": {
            "description": "Attachment delete failed (for example attachment does not belong to current scope).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notAllowed": {
                    "value": {
                      "error": {
                        "message": "Can't delete attachment",
                        "description": "User not in thread"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/attachments/{attachment_id}/download": {
      "get": {
        "tags": [
          "Attachments"
        ],
        "operationId": "downloadAttachment",
        "summary": "Download attachment",
        "description": "Redirects to a signed media service URL where the attachment can be downloaded.\nThe redirect URL includes a time-limited signature for authentication.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AttachmentId"
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to signed media service download URL.",
            "headers": {
              "location": {
                "description": "Signed media service URL for downloading the attachment.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundMessageOnly"
          }
        }
      }
    },
    "/attachments/{attachment_id}/download/preview": {
      "get": {
        "tags": [
          "Attachments"
        ],
        "operationId": "downloadAttachmentPreview",
        "summary": "Download attachment preview",
        "description": "Redirects to a signed media service URL where the attachment preview can be downloaded.\nThe redirect URL includes a time-limited signature for authentication.\nIf the preview is still being processed, the media service responds with 202 Accepted.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AttachmentId"
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to signed media service preview download URL.",
            "headers": {
              "location": {
                "description": "Signed media service URL for downloading the attachment preview.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundMessageOnly"
          }
        }
      }
    },
    "/users": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listUsers",
        "summary": "List users",
        "description": "Returns the users for the given `user_ids`, or searches the users the caller is related\nto by name or email with `query`. Pass exactly one of the two.\n\n**Search** matches a case-insensitive fragment of a user's name or email, and only among\nusers the caller has shared a thread or workspace with, mentioned, or looked up by email;\ndeleted and suspended users, and users who blocked the caller, are left out. It\nreturns at most 25 users, with\n`has_more: true` when the query should be narrowed.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/UserIds"
          },
          {
            "$ref": "#/components/parameters/UserSearchQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "User list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "data": [
                        {
                          "id": "u_tgJfNUiC1nDV4",
                          "object": "user",
                          "name": "Alice Finch",
                          "display_name": "Alice Finch",
                          "email": "alice.finch@example.com",
                          "avatar_small_path": "/uploads/alice-finch-avatar.png",
                          "avatar_small_url": "https://balsio.com/uploads/alice-finch-avatar.png",
                          "avatar_large_path": "/uploads/alice-finch-avatar-large.png"
                        }
                      ],
                      "object": "list",
                      "has_more": false,
                      "next_cursor": null,
                      "prev_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/users/{user_id}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getUser",
        "summary": "Retrieve user",
        "parameters": [
          {
            "$ref": "#/components/parameters/UserId"
          }
        ],
        "responses": {
          "200": {
            "description": "User object.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "u_tgJfNUiC1nDV4",
                      "object": "user",
                      "name": "Alice Finch",
                      "display_name": "Alice Finch",
                      "email": "alice.finch@example.com",
                      "avatar_small_path": "/uploads/alice-finch-avatar.png",
                      "avatar_small_url": "https://balsio.com/uploads/alice-finch-avatar.png",
                      "avatar_large_path": "/uploads/alice-finch-avatar-large.png",
                      "profile": {
                        "title": "Customer Success Lead",
                        "company": "Acme Inc.",
                        "website": "https://example.com",
                        "about_me": "Helping customers ship faster."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/scheduled_messages": {
      "get": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "listScheduledMessages",
        "summary": "List scheduled messages",
        "description": "Returns the authenticated user's pending scheduled messages.\nOptionally filter by thread.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/scheduled_messages\" \\\n  -H \"Authorization: Bearer sk_...\"\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    \"https://balsio.com/api/v1/scheduled_messages\",\n    headers={\"Authorization\": \"Bearer sk_...\"},\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/scheduled_messages\", {\n  headers: { Authorization: \"Bearer sk_...\" }\n});\nconst data = await response.json();\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ThreadIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled message list.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "createScheduledMessage",
        "summary": "Create scheduled message",
        "description": "Creates a scheduled message in the specified thread.\nThe message will be sent automatically at the specified `scheduled_at` time.\n\nSupports `Idempotency-Key` header for safe retries.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/scheduled_messages\" \\\n  -H \"Authorization: Bearer sk_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"thread_id\":\"th_fmn8SsKHoavown2s\",\"scheduled_at\":\"2026-03-01T10:00:00Z\",\"message\":{\"body\":\"Scheduled follow-up message\"}}'\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"thread_id\": \"th_fmn8SsKHoavown2s\",\n    \"scheduled_at\": \"2026-03-01T10:00:00Z\",\n    \"message\": {\"body\": \"Scheduled follow-up message\"},\n}\n\nresponse = requests.post(\n    \"https://balsio.com/api/v1/scheduled_messages\",\n    headers={\n        \"Authorization\": \"Bearer sk_...\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=payload,\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/scheduled_messages\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer sk_...\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    thread_id: \"th_fmn8SsKHoavown2s\",\n    scheduled_at: \"2026-03-01T10:00:00Z\",\n    message: { body: \"Scheduled follow-up message\" }\n  })\n});\nconst data = await response.json();\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScheduledMessageCreateRequest"
              },
              "examples": {
                "default": {
                  "summary": "Text message",
                  "value": {
                    "thread_id": "th_fmn8SsKHoavown2s",
                    "scheduled_at": "2026-03-01T10:00:00Z",
                    "message": {
                      "body": "Scheduled follow-up message"
                    }
                  }
                },
                "withAttachments": {
                  "summary": "Message with attachments",
                  "value": {
                    "thread_id": "th_fmn8SsKHoavown2s",
                    "scheduled_at": "2026-03-01T10:00:00Z",
                    "message": {
                      "body": "See attached report",
                      "attachments": [
                        {
                          "id": "att_DT7QcSFMRe5mlz"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scheduled message was created.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/scheduled_messages/{scheduled_message_id}": {
      "get": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "getScheduledMessage",
        "summary": "Retrieve scheduled message",
        "description": "Returns a single pending scheduled message by ID.\nOnly the user who created the scheduled message can retrieve it.\nProcessed scheduled messages are not returned.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduledMessageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled message details.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "updateScheduledMessage",
        "summary": "Update scheduled message",
        "description": "Updates the `scheduled_at` time and/or the `message` content of a\npending scheduled message. At least one field must be provided.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduledMessageId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScheduledMessageUpdateRequest"
              },
              "examples": {
                "updateTime": {
                  "summary": "Reschedule",
                  "value": {
                    "scheduled_at": "2026-03-02T14:00:00Z"
                  }
                },
                "updateBody": {
                  "summary": "Change message body",
                  "value": {
                    "message": {
                      "body": "Updated content"
                    }
                  }
                },
                "updateAttachments": {
                  "summary": "Update attachments",
                  "value": {
                    "message": {
                      "attachments": [
                        {
                          "id": "att_DT7QcSFMRe5mlz"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scheduled message was updated.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "deleteScheduledMessage",
        "summary": "Delete scheduled message",
        "description": "Deletes a pending scheduled message. The message will not be sent.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduledMessageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled message was deleted.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageDeleteResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/scheduled_messages/{scheduled_message_id}/send": {
      "post": {
        "tags": [
          "Scheduled Messages"
        ],
        "operationId": "sendScheduledMessage",
        "summary": "Send scheduled message immediately",
        "description": "Sends a pending scheduled message immediately, bypassing the\nscheduled time. The scheduled message is marked as processed\nand a regular message is created in the thread.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduledMessageId"
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled message was sent.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScheduledMessageSendResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "listEvents",
        "summary": "List canonical events",
        "description": "Returns canonical events visible to the authenticated integration.\nResults are sorted newest-first (descending by event id) and can be filtered by type and thread.\n",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS \"https://balsio.com/api/v1/events?limit=10\" \\\n  -H \"Authorization: Bearer sk_...\"\n"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    \"https://balsio.com/api/v1/events\",\n    headers={\"Authorization\": \"Bearer sk_...\"},\n    params={\"limit\": 10, \"type\": \"message.created\"},\n    timeout=30,\n)\nprint(response.json())\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://balsio.com/api/v1/events?limit=10\", {\n  headers: { Authorization: \"Bearer sk_...\" }\n});\nconst data = await response.json();\nconsole.log(data);\n"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/EventStartingAfter"
          },
          {
            "$ref": "#/components/parameters/EventEndingBefore"
          },
          {
            "$ref": "#/components/parameters/EventType"
          },
          {
            "$ref": "#/components/parameters/ThreadIdQuery"
          },
          {
            "$ref": "#/components/parameters/EventLimit"
          },
          {
            "$ref": "#/components/parameters/EventTimeout"
          }
        ],
        "responses": {
          "200": {
            "description": "Event list response.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "object": "list",
                      "data": [
                        {
                          "id": "e_032Kw4XA2DVxiGj72TxcaE",
                          "object": "event",
                          "type": "message.created",
                          "created_at": "2026-02-18T10:03:58.277962Z",
                          "data": {
                            "message": {
                              "id": "m_032Kw4XA2DVxiGj72TxcaE"
                            }
                          }
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null,
                      "previous_cursor": "e_032Kw4XA2DVxiGj72TxcaE"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/events/socket": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "openEventsSocket",
        "summary": "Open integration events WebSocket",
        "description": "Upgrades the HTTP connection to a read-only WebSocket that streams\ncanonical events for the authenticated integration. Each frame is a\nJSON-encoded `Event` — the same shape returned by `GET /events`.\n\nOpenAPI only describes the upgrade handshake. Message payloads,\nframe direction, and close codes are documented in the companion\nAsyncAPI specification linked via `x-async-api`.\n\nBehavior summary:\n- Auth: `Authorization: Bearer sk_...` (same as the REST API).\n- Resume: pass `?cursor=e_...` to start after a specific event id.\n  Omit to start from the newest event at connection time.\n- Version: send `X-Minor-Version`, as on REST. Without it, the stream\n  gets the oldest behavior; deprecated and rejected from 2027-01-10.\n- Read-only: any text or binary client frame closes the connection\n  with WebSocket code 1008.\n- Keepalive: the server closes a connection that receives no\n  client data for 60 seconds (code 1002, which also signals\n  protocol errors; reconnect with a backoff). Send WebSocket\n  protocol pings to stay connected; every 30 seconds is\n  recommended.\n- Revocation: revoking the integration closes its open connections\n  with WebSocket code 1008.\n",
        "x-async-api": "./events-socket.asyncapi.yaml",
        "parameters": [
          {
            "name": "Connection",
            "in": "header",
            "required": true,
            "description": "Must include the `Upgrade` token (case-insensitive). May be a\ncomma-separated list, e.g. `keep-alive, Upgrade`.\n",
            "schema": {
              "type": "string"
            },
            "example": "keep-alive, Upgrade"
          },
          {
            "name": "Upgrade",
            "in": "header",
            "required": true,
            "description": "Must be `websocket`.",
            "schema": {
              "type": "string",
              "enum": [
                "websocket"
              ]
            }
          },
          {
            "name": "Sec-WebSocket-Version",
            "in": "header",
            "required": true,
            "description": "RFC 6455 version; must be `13`.",
            "schema": {
              "type": "string",
              "enum": [
                "13"
              ]
            }
          },
          {
            "name": "Sec-WebSocket-Key",
            "in": "header",
            "required": true,
            "description": "Base64-encoded 16-byte client nonce (RFC 6455).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Resume after this event id. Omit to start from the newest event\nat connection time. Sending an empty string or a value without\nthe `e_` prefix rejects the upgrade with HTTP 400\n`invalid_cursor`.\n",
            "schema": {
              "type": "string",
              "pattern": "^e_.+"
            }
          },
          {
            "name": "X-Minor-Version",
            "in": "header",
            "required": false,
            "description": "API version. Without it, the stream gets the oldest behavior.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "Switching Protocols — WebSocket established. The server pushes\n`Event` JSON text frames. See the AsyncAPI document referenced\nby `x-async-api` for the message schema and close codes.\n"
          },
          "400": {
            "description": "Invalid cursor.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCursor": {
                    "value": {
                      "error": {
                        "type": "invalid_request_error",
                        "code": "invalid_cursor",
                        "message": "Can't connect events stream",
                        "description": "Invalid cursor"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Missing or invalid integration token.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingToken": {
                    "value": {
                      "error": {
                        "type": "invalid_request_error",
                        "code": "missing_token",
                        "message": "Can't connect events stream",
                        "description": "Missing or invalid token"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "integrationEvent": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "receiveIntegrationEvent",
        "summary": "Outbound integration webhook delivery",
        "description": "Balsio sends this webhook to integration-configured webhook URLs.\nEvents are delivered asynchronously and may be retried.\nDelivery scope by event type:\n- integration-auth create events:\n  - `channel.created`\n  - `attachment.created`\n  These are integration-scoped events (not participant fanout).\n- participant fanout events:\n  - `thread.left`\n  - `message.updated`\n  - `message.deleted`\n  - `message.reaction.created`\n  - `message.reaction.deleted`\n- request-scoped personal lifecycle events:\n  - `thread.archived`\n  - `thread.snoozed`\n  - `thread.moved`\n  - `thread.mark_read`\n  These do not fan out to participant integrations.\n- hybrid:\n  - `thread.created` can be sent for integration-auth create and also participant fanout.\n  - `message.created` can be sent for integration-auth create and also participant fanout.\nFor integration-auth fanout paths, the origin integration is excluded from participant fanout.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/XBalsioTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XBalsioSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              },
              "examples": {
                "subThreadCreated": {
                  "summary": "Sub-thread created",
                  "value": {
                    "id": "evt_032Kw4XA2DVxiGj72TxcaE",
                    "object": "event",
                    "type": "thread.created",
                    "created_at": "2026-02-18T10:05:00.000000Z",
                    "data": {
                      "thread": {
                        "id": "th_9xKpQ3mRvNwT2hYs",
                        "object": "thread",
                        "name": "Check out https://example.com/page",
                        "user_ids": [],
                        "users": [],
                        "users_count": 0,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "parent_thread_id": "th_fmn8SsKHoavown2s",
                        "parent_message_id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "joined": true,
                        "created_at": "2026-02-18T10:05:00.000000Z",
                        "updated_at": "2026-02-18T10:05:00.000000Z"
                      }
                    }
                  }
                },
                "threadArchived": {
                  "value": {
                    "id": "evt_032Kw4XA2DVxiGj72TxcaE",
                    "object": "event",
                    "type": "thread.archived",
                    "created_at": "2026-02-18T10:03:57.277962Z",
                    "data": {
                      "thread_id": "th_fmn8SsKHoavown2s",
                      "archived_at": "2026-02-18T10:03:57.277962Z"
                    }
                  }
                },
                "messageUpdated": {
                  "value": {
                    "id": "evt_032Kw5BC3EWyjHk83UydbF",
                    "object": "event",
                    "type": "message.updated",
                    "created_at": "2026-02-18T10:05:10.277962Z",
                    "data": {
                      "message": {
                        "id": "m_032Kw4XA2DVxiGj72TxcaE",
                        "object": "message",
                        "thread_id": "th_fmn8SsKHoavown2s",
                        "body": "Updated body",
                        "user_id": "u_tgJfNUiC1nDV4",
                        "created_at": "2026-02-18T10:03:57.277962Z"
                      },
                      "thread": {
                        "id": "th_fmn8SsKHoavown2s",
                        "object": "thread",
                        "name": "Customer onboarding",
                        "user_ids": [
                          "u_tgJfNUiC1nDV4",
                          "u_zLqW4mDNJBHc2"
                        ],
                        "users": [
                          {
                            "user_id": "u_tgJfNUiC1nDV4",
                            "roles": [
                              "creator",
                              "owner"
                            ]
                          },
                          {
                            "user_id": "u_zLqW4mDNJBHc2",
                            "roles": []
                          }
                        ],
                        "users_count": 2,
                        "settings": {
                          "is_sharing_enabled": false
                        },
                        "created_at": "2026-02-18T10:03:57.277962Z",
                        "updated_at": "2026-02-18T10:05:10.277962Z"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receiver accepted the event."
          },
          "204": {
            "description": "Receiver accepted with no content."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk_token"
      }
    },
    "parameters": {
      "ThreadId": {
        "name": "thread_id",
        "in": "path",
        "required": true,
        "description": "Prefixed thread id (`th_...`).",
        "schema": {
          "type": "string",
          "pattern": "^th_.+"
        }
      },
      "ThreadIdQueryRequired": {
        "name": "thread_id",
        "in": "query",
        "required": true,
        "description": "Prefixed thread id (`th_...`).",
        "schema": {
          "type": "string",
          "pattern": "^th_.+"
        }
      },
      "ThreadIdQuery": {
        "name": "thread_id",
        "in": "query",
        "required": false,
        "description": "Optional prefixed thread id (`th_...`).",
        "schema": {
          "type": "string",
          "pattern": "^th_.+"
        }
      },
      "MessageId": {
        "name": "message_id",
        "in": "path",
        "required": true,
        "description": "Prefixed message id (`m_...`).",
        "schema": {
          "type": "string",
          "pattern": "^m_.+"
        }
      },
      "ReactionName": {
        "name": "name",
        "in": "path",
        "required": true,
        "description": "Reaction name.",
        "schema": {
          "type": "string"
        }
      },
      "UserId": {
        "name": "user_id",
        "in": "path",
        "required": true,
        "description": "Prefixed user id (`u_...`).",
        "schema": {
          "type": "string",
          "pattern": "^u_.+"
        }
      },
      "ChannelId": {
        "name": "channel_id",
        "in": "query",
        "required": false,
        "description": "Optional prefixed channel id (`ch_...`).",
        "schema": {
          "type": "string",
          "pattern": "^ch_.+"
        }
      },
      "ParentThreadId": {
        "name": "parent_thread_id",
        "in": "query",
        "required": false,
        "description": "List sub-threads of a given parent thread (`th_...`). Mutually exclusive with `channel_id` — do not pass both.",
        "schema": {
          "type": "string",
          "pattern": "^th_.+"
        }
      },
      "ParticipantIds": {
        "name": "participant_ids",
        "in": "query",
        "required": false,
        "description": "Comma-separated prefixed user ids (`u_...`), up to 100. Narrows the listed channel to threads that include every one of them; the caller's own id is neither needed nor implied. In a thread that hides its participants, only members visible to the caller match; sub-threads never match. Not allowed with `parent_thread_id`.",
        "schema": {
          "type": "string"
        }
      },
      "OneOnOneWith": {
        "name": "one_on_one_with",
        "in": "query",
        "required": false,
        "description": "Prefixed user id (`u_...`). Narrows the listed channel to the caller's one-on-one thread with that user. Not allowed with `parent_thread_id`.",
        "schema": {
          "type": "string",
          "pattern": "^u_.+"
        }
      },
      "ShareKeyPath": {
        "name": "share_key",
        "in": "path",
        "required": true,
        "description": "Share key from a thread share link or a workspace join link.",
        "schema": {
          "type": "string"
        }
      },
      "WorkspaceRolePath": {
        "name": "role",
        "in": "path",
        "required": true,
        "description": "Workspace role. `owner` is the only role today.",
        "schema": {
          "type": "string",
          "enum": [
            "owner"
          ]
        }
      },
      "ChannelIdPath": {
        "name": "channel_id",
        "in": "path",
        "required": true,
        "description": "Prefixed channel id (`ch_...`) for a visible channel.",
        "schema": {
          "type": "string",
          "pattern": "^ch_.+"
        }
      },
      "IntegrationIdPath": {
        "name": "integration_id",
        "in": "path",
        "required": true,
        "description": "Prefixed integration id (`int_...`) of an integration visible to the caller.",
        "schema": {
          "type": "string",
          "pattern": "^int_.+"
        }
      },
      "AttachmentId": {
        "name": "attachment_id",
        "in": "path",
        "required": true,
        "description": "Prefixed attachment id (`att_...`) visible to current integration scope.",
        "schema": {
          "type": "string",
          "pattern": "^att_.+"
        }
      },
      "ScheduledMessageId": {
        "name": "scheduled_message_id",
        "in": "path",
        "required": true,
        "description": "Prefixed scheduled message id (`sm_...`).",
        "schema": {
          "type": "string",
          "pattern": "^sm_.+"
        }
      },
      "Role": {
        "name": "role",
        "in": "path",
        "required": true,
        "description": "Thread membership role.\n- `owner`: can be granted/revoked with role endpoints.\n- `creator`: automatically set for the thread creator and cannot be granted/revoked.\n",
        "schema": {
          "type": "string",
          "enum": [
            "owner"
          ],
          "example": "owner"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Maximum number of records to return.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "EventLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Maximum number of events to return.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        }
      },
      "EventTimeout": {
        "name": "timeout",
        "in": "query",
        "required": false,
        "description": "Long-poll timeout in seconds. When provided and no events are currently available,\nthe request waits until new events arrive or timeout is reached.\nSupported for baseline/`ending_before` polling. Invalid when combined with `starting_after`.\n",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 30,
          "default": 0
        }
      },
      "EventStartingAfter": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "Cursor pointing to an event ID (`e_...`). Returns events that come after this one\nin the result list order. Because events are sorted newest-first, this gives you\n*older* events — use this to paginate backward into history.\nMutually exclusive with `ending_before`.\n",
        "schema": {
          "type": "string",
          "pattern": "^e_.+"
        }
      },
      "EventEndingBefore": {
        "name": "ending_before",
        "in": "query",
        "required": false,
        "description": "Cursor pointing to an event ID (`e_...`). Returns the page of events immediately\nnewer than this one (adjacent to the cursor), in newest-first order. Paginate forward\ncontiguously by passing each response's `previous_cursor` back as `ending_before`.\nMutually exclusive with `starting_after`.\n",
        "schema": {
          "type": "string",
          "pattern": "^e_.+"
        }
      },
      "EventType": {
        "name": "type",
        "in": "query",
        "required": false,
        "description": "Filter by canonical event type.",
        "schema": {
          "type": "string",
          "enum": [
            "thread.created",
            "thread.updated",
            "thread.moved",
            "thread.joined",
            "thread.left",
            "thread.read",
            "thread.preferences.updated",
            "thread.deleted",
            "message.created",
            "message.updated",
            "message.deleted",
            "message.reaction.created",
            "message.reaction.deleted",
            "user.updated",
            "channel.created",
            "channel.updated",
            "channel.deleted",
            "workspace.created",
            "workspace.updated",
            "workspace.deleted",
            "workspace.summary_updated",
            "workspace.members_changed",
            "scheduled_message.created",
            "scheduled_message.updated",
            "scheduled_message.deleted"
          ]
        }
      },
      "BeforeId": {
        "name": "before_id",
        "in": "query",
        "required": false,
        "description": "Cursor-based pagination token for fetching older records.",
        "schema": {
          "type": "string"
        }
      },
      "UserIds": {
        "name": "user_ids",
        "in": "query",
        "required": false,
        "description": "Comma-separated prefixed user ids (for example `u_...`).",
        "schema": {
          "type": "string"
        }
      },
      "UserSearchQuery": {
        "name": "query",
        "in": "query",
        "required": false,
        "description": "Case-insensitive fragment of a related user's name or email, at most 200 bytes.",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Idempotency for safely deduplicating retried requests.\n",
        "schema": {
          "type": "string"
        }
      },
      "XBalsioTimestampHeader": {
        "name": "x-balsio-timestamp",
        "in": "header",
        "required": true,
        "description": "Webhook unix timestamp header.\nThe same value is also sent as the deprecated `x-birdy-timestamp`, which stops being sent after 2027-01-10.\n",
        "schema": {
          "type": "string",
          "example": "1771409037"
        }
      },
      "XBalsioSignatureHeader": {
        "name": "x-balsio-signature",
        "in": "header",
        "required": true,
        "description": "Webhook signature header in format `t=<timestamp>,v1=<hex_digest>`.\nThe same value is also sent as the deprecated `x-birdy-signature`, which stops being sent after 2027-01-10.\n",
        "schema": {
          "type": "string",
          "example": "t=1771409037,v1=8543e8d69262e24b1a25eb4cab298a6e7b447312cbf6e639ca35d71028f241bb"
        }
      }
    },
    "headers": {
      "XRequestId": {
        "description": "Request identifier for troubleshooting.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Event": {
        "type": "object",
        "required": [
          "id",
          "object",
          "type",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^e_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "event"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "thread.created",
              "thread.updated",
              "thread.moved",
              "thread.joined",
              "thread.left",
              "thread.read",
              "thread.preferences.updated",
              "thread.deleted",
              "message.created",
              "message.updated",
              "message.deleted",
              "message.reaction.created",
              "message.reaction.deleted",
              "user.updated",
              "channel.created",
              "channel.updated",
              "channel.deleted",
              "workspace.created",
              "workspace.updated",
              "workspace.deleted",
              "workspace.summary_updated",
              "workspace.members_changed",
              "scheduled_message.created",
              "scheduled_message.updated",
              "scheduled_message.deleted"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "EventListResponse": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor",
          "previous_cursor"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page of older events. Pass as `starting_after` to paginate backward.\nNull when there are no more older events.\n"
          },
          "previous_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor pointing to the newest event on this page. Pass as `ending_before` to fetch\nthe next contiguous page of newer events. Null when the page is empty.\n"
          }
        }
      },
      "ThreadPreview": {
        "type": "object",
        "description": "Preview of the thread behind a share link.",
        "required": [
          "id",
          "object",
          "name",
          "member_count"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "thread_preview"
            ]
          },
          "name": {
            "type": "string"
          },
          "member_count": {
            "type": "integer",
            "description": "How many participants the thread currently has."
          },
          "image": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ThreadImage"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "ThreadUser": {
        "type": "object",
        "required": [
          "user_id",
          "roles"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "creator",
                "owner",
                "external"
              ]
            }
          }
        }
      },
      "ThreadReadReceipt": {
        "type": "object",
        "required": [
          "message_id",
          "read_at"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "read_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ThreadSettings": {
        "type": "object",
        "description": "Thread behavior flags. Every key except `is_sharing_enabled` is omitted when false, so treat a missing key as false. All keys default to false, except `participants_can_add_users`, which defaults to true on new non-workspace threads, and `is_participant_notifications_disabled`, which defaults to true on every new thread.",
        "required": [
          "is_sharing_enabled"
        ],
        "properties": {
          "is_sharing_enabled": {
            "type": "boolean",
            "default": false,
            "description": "True when the thread has an active public share link (see the thread's `share_link` field). Computed from the share key and always present. Only group threads can enable sharing. Cannot be enabled for threads in a workspace."
          },
          "is_email_digests_disabled": {
            "type": "boolean",
            "default": false,
            "description": "Controls email digest cadence. False (default): thread activity is emailed in batched digests roughly every 5 minutes. True: those per-message digest emails stop; group-thread activity is instead summarized in a weekly email (one-on-one threads have no weekly digest, so they get no digest emails while this is enabled). Digest emails only go to members who were not reached by a push notification (typically members without the mobile app). Has no effect on push notifications — @mentions and regular messages still push immediately."
          },
          "is_participant_notifications_disabled": {
            "type": "boolean",
            "default": false,
            "description": "When true, membership system messages in the thread (\"X joined\", \"X left\", \"X added/removed Y\") are suppressed. The \"added you to this chat\" push is sent either way. No system message produces a push or an email digest entry, whatever this setting holds; notifications for regular user messages are not affected, and system messages that are not about membership — rename, description change, visibility flip, move into a workspace and group-thread creation — are still posted. Enabling `hide_participants` forces this setting to true, and it can't be set back to false while participants stay hidden (validation error). It stays true after `hide_participants` is turned off. Defaults to true on every new thread; pass false at creation to post membership messages. A `hide_participants: true` in the same request wins over a false sent alongside it."
          },
          "disable_participant_messaging": {
            "type": "boolean",
            "default": false,
            "description": "When true, only thread owners can post messages in this thread; other members receive an error. On a public workspace thread the workspace's admins can post as well. Does not restrict reading, reactions, editing, or deleting existing messages. The setting does not cascade to sub-threads — members can still reply there (use `disable_participant_sub_thread_messaging` to also restrict those)."
          },
          "disable_participant_sub_thread_messaging": {
            "type": "boolean",
            "default": false,
            "description": "When true on a parent thread, only its owners can create messages in its sub-threads (error code `sub_thread_messaging_disabled`). On a public workspace thread the workspace's admins can post as well. Non-owners can still read and join sub-threads."
          },
          "hide_participants": {
            "type": "boolean",
            "default": false,
            "description": "Applies to regular top-level threads: when true, non-owner viewers see only thread owners in `users` and `user_ids`, while owners see the full participant list; `users_count` still reflects the true total. Enabling it also sets `is_participant_notifications_disabled` to true. Sub-threads and workspace-channel threads always return empty `users`/`user_ids` and `users_count: 0` regardless of this setting."
          },
          "participants_can_add_users": {
            "type": "boolean",
            "default": false,
            "description": "When false, only owners can add users to a group thread. When true (the creation default for new non-workspace threads), any member can add users. Removing users and granting roles remain owner-only. Never applies to one-on-one threads or sub-threads. Like every key except `is_sharing_enabled`, omitted from responses when false."
          }
        }
      },
      "Thread": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name",
          "user_ids",
          "users",
          "users_count",
          "settings",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "thread"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "description": "Optional thread description text.",
            "type": [
              "string",
              "null"
            ]
          },
          "last_message_excerpt": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          },
          "last_author_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          },
          "last_message_created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          },
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadUser"
            }
          },
          "users_count": {
            "type": "integer"
          },
          "read_receipts": {
            "type": "object",
            "description": "Per-user read state, keyed by user id. In threads whose settings have `hide_participants: true`, non-owners get only their own entry; when nothing remains, the key is omitted entirely and the local state should be kept. Sub-threads are governed by their parent thread's settings.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ThreadReadReceipt"
            }
          },
          "settings": {
            "$ref": "#/components/schemas/ThreadSettings"
          },
          "share_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "image": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ThreadImage"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "parent_thread_id": {
            "description": "ID of the parent thread. Present only for sub-threads.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^th_.+"
          },
          "parent_message_id": {
            "description": "ID of the parent message this sub-thread was created from. Present only for sub-threads.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          },
          "workspace_channel_id": {
            "description": "ID of the workspace channel this thread lives in, or `null` outside a workspace.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+"
          },
          "workspace": {
            "$ref": "#/components/schemas/WorkspaceSummary"
          },
          "workspace_visibility": {
            "description": "Who can reach the thread inside its workspace. `public` is browsable and joinable by every workspace member; `private` is reachable only by its participants. Omitted outside a workspace.",
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "one_on_one_user_id_pair": {
            "description": "Sorted, comma-separated pair of user IDs (e.g. `u_abc,u_xyz`). Present only on one-on-one threads. Use this field to determine whether a thread is one-on-one.",
            "type": "string"
          },
          "joined": {
            "description": "Always present for sub-threads. Indicates whether the authenticated user follows this sub-thread. Since sub-thread `user_ids` is always empty, this is the only way to determine participation.",
            "type": "boolean"
          },
          "idempotency_key": {
            "type": "string"
          },
          "thread_user_preferences": {
            "description": "Per-user preferences for this thread. Only present when the authenticated user has preferences set (e.g. has snoozed or muted the thread).",
            "$ref": "#/components/schemas/ThreadUserPreferences"
          }
        }
      },
      "ThreadUserPreferences": {
        "type": "object",
        "required": [
          "thread_id"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "snoozed": {
            "description": "Present when the user has snoozed this thread at some point.",
            "type": "object",
            "properties": {
              "snoozed_until": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "expired_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "muted": {
            "description": "Present when the user has muted this thread at some point.",
            "type": "object",
            "properties": {
              "muted_until": {
                "description": "Datetime until muted, or `\"forever\"` for permanent mute.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "sub_text": {
            "description": "Custom sub-text display for the thread.",
            "type": "object",
            "properties": {
              "code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "message": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "surfaced": {
            "description": "Present when the thread has been surfaced to the user.",
            "type": "object",
            "properties": {
              "surfaced_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "read": {
            "description": "The user's read receipt for this thread. `message_id` is the last message they read, or `null` when they marked the thread unread. `read_at` is when the receipt was last written. The server keeps the last write, so take the receipt from the most recently synced row: `read_at` values written by different servers can be a few milliseconds out of order.",
            "type": "object",
            "properties": {
              "message_id": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^m_.+"
              },
              "read_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "ThreadListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          }
        ]
      },
      "MessageReaction": {
        "type": "object",
        "required": [
          "created_at"
        ],
        "properties": {
          "reaction_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{32}$",
            "description": "Stable pseudonym for the entry, unique per (user, message, reaction name). Key and dedupe entries by `reaction_id`, falling back to `user_id` on payloads recorded before `reaction_id` existed."
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+",
            "description": "Present when the viewer may identify the reactor. In threads whose settings have `hide_participants: true`, non-owners see it only on their own entries; anonymous entries carry `reaction_id` without `user_id`."
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessageAttachment": {
        "type": "object",
        "required": [
          "attachment_id",
          "type"
        ],
        "properties": {
          "attachment_id": {
            "type": "string",
            "pattern": "^att_.+"
          },
          "type": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "alt": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "preview_size": {
            "type": "integer"
          },
          "preview_width": {
            "type": "integer"
          },
          "preview_height": {
            "type": "integer"
          },
          "preview_status": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "path": {
            "type": "string",
            "description": "Relative path that redirects to the attachment download location."
          },
          "preview_path": {
            "type": "string",
            "description": "Relative path that redirects to the attachment preview download location."
          }
        }
      },
      "Message": {
        "type": "object",
        "required": [
          "id",
          "object",
          "thread_id",
          "user_id",
          "body",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "message"
            ]
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "body": {
            "type": "string",
            "description": "Message text. May contain @-mentions as markdown links with the `birdy://` scheme: `[@DisplayName](birdy://users/<user_id>)`.\n"
          },
          "reply_to_message_excerpt": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "edited_at": {
            "description": "Timestamp of when the message was last edited. Only present after a message has been updated.",
            "type": "string",
            "format": "date-time"
          },
          "reply_to": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          },
          "reactions": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/MessageReaction"
              }
            }
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageAttachment"
            }
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true
          },
          "sub_thread_id": {
            "description": "ID of the sub-thread created from this message, if any.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^th_.+"
          },
          "mentioned_user_ids": {
            "description": "IDs of users mentioned in the message. Only present when the message contains mentions.",
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "MessageTombstone": {
        "description": "Minimal message object returned for deleted messages. Contains no body.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "object",
          "thread_id",
          "user_id",
          "created_at",
          "deleted_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "message"
            ]
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "sub_thread_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^th_.+"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "MessageListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Message"
                    },
                    {
                      "$ref": "#/components/schemas/MessageTombstone"
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "MessageCreatePayload": {
        "type": "object",
        "description": "At least one of `body` or `attachments` must be provided.\n",
        "anyOf": [
          {
            "required": [
              "body"
            ]
          },
          {
            "required": [
              "attachments"
            ]
          }
        ],
        "properties": {
          "body": {
            "type": "string",
            "description": "Message text. To @-mention a user, include a markdown link with the `birdy://` scheme: `[@DisplayName](birdy://users/<user_id>)`. Only `birdy://users/` links are recognized as mentions; other link schemes are ignored. Mentioning a user outside the thread is allowed if that user is known to the author (e.g. they share a thread); otherwise the mention is silently ignored.\n",
            "example": "Hey [@Alice Finch](birdy://users/u_tgJfNUiC1nDV4), can you take a look?"
          },
          "reply_to": {
            "type": "string",
            "pattern": "^m_.+",
            "description": "Prefixed message id to reply to."
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^att_.+"
                }
              }
            }
          }
        }
      },
      "MessageUpdatePayload": {
        "type": "object",
        "properties": {
          "body": {
            "type": "string",
            "description": "Message text. To @-mention a user, include a markdown link with the `birdy://` scheme: `[@DisplayName](birdy://users/<user_id>)`. Only `birdy://users/` links are recognized as mentions; other link schemes are ignored. Mentioning a user outside the thread is allowed if that user is known to the author (e.g. they share a thread); otherwise the mention is silently ignored.\n",
            "example": "Hey [@Alice Finch](birdy://users/u_tgJfNUiC1nDV4), can you take a look?"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ThreadMessageCreateRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/MessageCreatePayload"
          }
        }
      },
      "MessageUpdateRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/MessageUpdatePayload"
          }
        }
      },
      "MessageCreateResponse": {
        "type": "object",
        "required": [
          "message",
          "thread"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "MessageUpdateResponse": {
        "type": "object",
        "required": [
          "message",
          "thread"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "MessageDeleteResponse": {
        "type": "object",
        "required": [
          "message",
          "message_id",
          "thread",
          "deleted_at"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/MessageTombstone"
          },
          "message_id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ReactionCreateRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ReactionAddResponse": {
        "type": "object",
        "required": [
          "message_id",
          "thread_id",
          "user_id",
          "name",
          "created_at"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "name": {
            "type": "string"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ReactionRemoveResponse": {
        "type": "object",
        "required": [
          "message_id",
          "thread_id",
          "user_id",
          "name"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "MessageSummary": {
        "type": "object",
        "required": [
          "id",
          "thread_id",
          "body",
          "object"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "body": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "enum": [
              "message"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "reply_to_message_excerpt": {
            "type": [
              "string",
              "null"
            ]
          },
          "sub_thread_id": {
            "description": "ID of the sub-thread created from this message, if any.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^th_.+"
          }
        }
      },
      "ThreadCreateRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RegularThreadCreateRequest"
          },
          {
            "$ref": "#/components/schemas/SubThreadCreateRequest"
          }
        ]
      },
      "RegularThreadCreateRequest": {
        "type": "object",
        "required": [
          "recipient_emails",
          "thread",
          "message"
        ],
        "properties": {
          "recipient_emails": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Required, but may be null. On a workspace thread, null adds every workspace member, while `[]` leaves the creator as the sole participant; a non-empty list adds those recipients — members join normally and non-members join as external participants, with unknown emails invited as new users. A non-workspace thread treats null as an empty list."
          },
          "channel_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+",
            "description": "Channel the thread is filed in. A workspace channel id creates a workspace thread; any other channel files a personal one. Omit or send null for no channel placement."
          },
          "thread": {
            "type": "object",
            "properties": {
              "name": {
                "description": "Thread name. Required for group threads. Omit for one-on-one threads (single recipient, no name).",
                "type": "string"
              },
              "workspace_visibility": {
                "description": "Visibility of a thread created in a workspace, `public` (the default) or `private`. Rejected unless `channel_id` is a workspace.",
                "type": "string",
                "enum": [
                  "public",
                  "private"
                ]
              },
              "settings": {
                "type": "object",
                "description": "Initial thread settings, applied atomically at creation; see `ThreadSettings` for the meaning of each flag. Group threads only — one-on-one threads reject settings (`settings_not_supported_for_one_on_one`). Values must be literal booleans; omitted keys keep the server defaults. Sharing is not supported here: enable it after creation through the thread-settings update (`is_sharing_enabled: true` is rejected with `sharing_not_supported_at_creation`). Threads created in a workspace allow only `is_email_digests_disabled`, `disable_participant_messaging`, `disable_participant_sub_thread_messaging` and `is_participant_notifications_disabled` (`setting_not_supported_in_workspace` otherwise). Enabling `hide_participants` also forces `is_participant_notifications_disabled` to true.",
                "properties": {
                  "is_email_digests_disabled": {
                    "type": "boolean"
                  },
                  "is_participant_notifications_disabled": {
                    "type": "boolean"
                  },
                  "disable_participant_messaging": {
                    "type": "boolean"
                  },
                  "disable_participant_sub_thread_messaging": {
                    "type": "boolean"
                  },
                  "hide_participants": {
                    "type": "boolean"
                  },
                  "participants_can_add_users": {
                    "type": "boolean"
                  }
                }
              }
            }
          },
          "message": {
            "type": "object",
            "description": "At least one of `body` or `attachments` must be provided.\n",
            "anyOf": [
              {
                "required": [
                  "body"
                ]
              },
              {
                "required": [
                  "attachments"
                ]
              }
            ],
            "properties": {
              "body": {
                "type": "string"
              },
              "attachments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^att_.+"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "SubThreadCreateRequest": {
        "type": "object",
        "required": [
          "parent_thread_id",
          "parent_message_id",
          "message"
        ],
        "properties": {
          "parent_thread_id": {
            "description": "ID of the parent thread. Must reference an existing non-sub-thread.",
            "type": "string",
            "pattern": "^th_.+"
          },
          "parent_message_id": {
            "description": "ID of the parent message. Must reference a message in the parent thread.",
            "type": "string",
            "pattern": "^m_.+"
          },
          "message": {
            "type": "object",
            "description": "At least one of `body` or `attachments` must be provided.\n",
            "anyOf": [
              {
                "required": [
                  "body"
                ]
              },
              {
                "required": [
                  "attachments"
                ]
              }
            ],
            "properties": {
              "body": {
                "type": "string"
              },
              "attachments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^att_.+"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ThreadCreateResponse": {
        "type": "object",
        "required": [
          "thread",
          "message"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "message": {
            "$ref": "#/components/schemas/MessageSummary"
          },
          "thread_in_channels": {
            "description": "Channel placements for the new thread. Present on regular thread creation.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          },
          "threads_in_channels": {
            "description": "Channel placements for the new sub-thread. Present on sub-thread creation.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          },
          "parent_message": {
            "description": "The updated parent message with `sub_thread_id` set. Present on sub-thread creation.",
            "$ref": "#/components/schemas/Message"
          }
        }
      },
      "ThreadAddUsersRequest": {
        "type": "object",
        "required": [
          "emails"
        ],
        "properties": {
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          }
        }
      },
      "ThreadRemoveUsersRequest": {
        "type": "object",
        "required": [
          "user_ids"
        ],
        "properties": {
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          }
        }
      },
      "ThreadRoleMutationRequest": {
        "type": "object",
        "required": [
          "user_ids"
        ],
        "properties": {
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          }
        }
      },
      "ThreadIdWithMessageId": {
        "type": "object",
        "required": [
          "thread_id",
          "message_id"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          }
        }
      },
      "ThreadArchiveRequest": {
        "type": "object",
        "required": [
          "thread_ids",
          "last_message_ids"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "last_message_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadIdWithMessageId"
            }
          },
          "archived_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional archive timestamp. Must include fractional seconds. Returned placement timestamps may be later to supersede the current source placement."
          }
        }
      },
      "ThreadSnoozeRequest": {
        "type": "object",
        "required": [
          "thread_ids",
          "snoozed_until",
          "last_message_ids"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time",
            "description": "Must be at least 2 seconds in the future."
          },
          "last_message_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadIdWithMessageId"
            }
          },
          "snoozed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional snooze timestamp. Must include fractional seconds."
          }
        }
      },
      "ThreadMoveRequest": {
        "type": "object",
        "required": [
          "thread_ids",
          "from_channel_id",
          "to_channel_id"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "from_channel_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+"
          },
          "to_channel_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+"
          },
          "moved_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional move timestamp. Must include fractional seconds."
          }
        }
      },
      "ThreadMuteRequest": {
        "type": "object",
        "required": [
          "thread_ids",
          "muted_until"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "muted_until": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 8601 datetime (must be at least 2 seconds in the future), `\"forever\"`, or `null` to unmute."
          },
          "muted_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional mute timestamp. Must include fractional seconds."
          }
        }
      },
      "ThreadReadRequest": {
        "type": "object",
        "required": [
          "thread_ids",
          "message_ids"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "message_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadIdWithMessageId"
            }
          }
        }
      },
      "ThreadReadResponse": {
        "type": "object",
        "required": [
          "threads"
        ],
        "properties": {
          "threads": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "thread_id",
                "message_id"
              ],
              "properties": {
                "thread_id": {
                  "type": "string",
                  "pattern": "^th_.+"
                },
                "message_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "pattern": "^m_.+"
                }
              }
            }
          }
        }
      },
      "ThreadMarkReadRequest": {
        "type": "object",
        "required": [
          "message_id"
        ],
        "properties": {
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+",
            "description": "Message id to mark as read, or `null` to mark as unread."
          }
        }
      },
      "ThreadInChannel": {
        "type": "object",
        "required": [
          "channel_id",
          "thread_id",
          "status",
          "updated_at"
        ],
        "properties": {
          "channel_id": {
            "type": "string",
            "pattern": "^ch_.+"
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "status": {
            "type": "string",
            "enum": [
              "present",
              "absent"
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ThreadArchiveResponse": {
        "type": "object",
        "required": [
          "thread_ids",
          "thread_in_channels"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "thread_in_channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          }
        }
      },
      "ThreadSnoozeResponse": {
        "type": "object",
        "required": [
          "snoozed_thread_ids",
          "thread_in_channels"
        ],
        "properties": {
          "snoozed_thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "thread_in_channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          }
        }
      },
      "ThreadMoveResponse": {
        "type": "object",
        "required": [
          "thread_ids",
          "thread_in_channels"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          },
          "thread_in_channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          }
        }
      },
      "ThreadMuteResponse": {
        "type": "object",
        "required": [
          "thread_ids"
        ],
        "properties": {
          "thread_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^th_.+"
            }
          }
        }
      },
      "ThreadMarkReadResponse": {
        "type": "object",
        "required": [
          "thread_id",
          "message_id"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          }
        }
      },
      "WebhookThreadCreateData": {
        "type": "object",
        "required": [
          "thread",
          "message"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "message": {
            "$ref": "#/components/schemas/MessageSummary"
          },
          "thread_in_channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "WebhookMessageUpdatedData": {
        "type": "object",
        "required": [
          "message",
          "thread"
        ],
        "properties": {
          "message": {
            "$ref": "#/components/schemas/MessageSummary"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "WebhookMessageDeletedData": {
        "type": "object",
        "required": [
          "message_id",
          "thread",
          "deleted_at"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookMessageReactionCreatedData": {
        "type": "object",
        "required": [
          "reaction"
        ],
        "properties": {
          "reaction": {
            "type": "object",
            "required": [
              "message_id",
              "thread_id",
              "name",
              "created_at"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^m_.+"
              },
              "thread_id": {
                "type": "string",
                "pattern": "^th_.+"
              },
              "reaction_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$",
                "description": "Stable pseudonym for the reaction, unique per (user, message, reaction name). Key reactions by `reaction_id`, falling back to `user_id` on payloads recorded before `reaction_id` existed."
              },
              "user_id": {
                "type": "string",
                "pattern": "^u_.+",
                "description": "Omitted in threads whose settings have `hide_participants: true` when the integration's user is not a thread owner; such anonymous payloads carry `reaction_id` without `user_id`."
              },
              "name": {
                "type": "string"
              },
              "variant": {
                "type": "string"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "WebhookMessageReactionDeletedData": {
        "type": "object",
        "required": [
          "reaction"
        ],
        "properties": {
          "reaction": {
            "type": "object",
            "required": [
              "message_id",
              "thread_id",
              "name"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^m_.+"
              },
              "thread_id": {
                "type": "string",
                "pattern": "^th_.+"
              },
              "reaction_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$",
                "description": "Stable pseudonym for the reaction, unique per (user, message, reaction name). Matches the `reaction_id` delivered when the reaction was created."
              },
              "user_id": {
                "type": "string",
                "pattern": "^u_.+",
                "description": "Omitted in threads whose settings have `hide_participants: true` when the integration's user is not a thread owner; such anonymous payloads carry `reaction_id` without `user_id`."
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "WebhookThreadArchivedData": {
        "type": "object",
        "required": [
          "thread_id",
          "archived_at"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "archived_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookThreadSnoozedData": {
        "type": "object",
        "required": [
          "thread_id",
          "snoozed_at",
          "snoozed_until"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "snoozed_at": {
            "type": "string",
            "format": "date-time"
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookThreadMovedData": {
        "type": "object",
        "required": [
          "thread_id",
          "moved_at",
          "from_channel_id",
          "to_channel_id"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "moved_at": {
            "type": "string",
            "format": "date-time"
          },
          "from_channel_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+"
          },
          "to_channel_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^ch_.+"
          }
        }
      },
      "WebhookThreadMarkReadData": {
        "type": "object",
        "required": [
          "thread_id",
          "message_id",
          "user_id",
          "read_at"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "read_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookThreadLeftData": {
        "type": "object",
        "required": [
          "thread_id",
          "user_ids",
          "left_at"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          },
          "left_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookChannelCreatedData": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "type": "object",
            "required": [
              "id",
              "object",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^ch_.+"
              },
              "object": {
                "type": "string",
                "enum": [
                  "channel"
                ]
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "WebhookAttachmentCreatedData": {
        "type": "object",
        "required": [
          "attachment"
        ],
        "properties": {
          "attachment": {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^att_.+"
              },
              "object": {
                "type": "string",
                "enum": [
                  "attachment"
                ]
              },
              "upload_url": {
                "type": "string",
                "format": "uri",
                "description": "Signed URL to upload the file to."
              }
            }
          }
        }
      },
      "WebhookEventData": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/WebhookThreadCreateData"
          },
          {
            "$ref": "#/components/schemas/WebhookMessageUpdatedData"
          },
          {
            "$ref": "#/components/schemas/WebhookMessageDeletedData"
          },
          {
            "$ref": "#/components/schemas/WebhookMessageReactionCreatedData"
          },
          {
            "$ref": "#/components/schemas/WebhookMessageReactionDeletedData"
          },
          {
            "$ref": "#/components/schemas/WebhookThreadArchivedData"
          },
          {
            "$ref": "#/components/schemas/WebhookThreadSnoozedData"
          },
          {
            "$ref": "#/components/schemas/WebhookThreadMovedData"
          },
          {
            "$ref": "#/components/schemas/WebhookThreadMarkReadData"
          },
          {
            "$ref": "#/components/schemas/WebhookThreadLeftData"
          },
          {
            "$ref": "#/components/schemas/WebhookChannelCreatedData"
          },
          {
            "$ref": "#/components/schemas/WebhookAttachmentCreatedData"
          }
        ]
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "object",
          "type",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "event"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "thread.created",
              "message.created",
              "channel.created",
              "attachment.created",
              "thread.archived",
              "thread.snoozed",
              "thread.moved",
              "thread.mark_read",
              "thread.left",
              "message.updated",
              "message.deleted",
              "message.reaction.created",
              "message.reaction.deleted"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/WebhookEventData"
          }
        }
      },
      "ThreadVisibilityUpdateRequest": {
        "type": "object",
        "required": [
          "workspace_visibility"
        ],
        "properties": {
          "workspace_visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "Required. Unlike thread creation and the move into a workspace, this call has no default — omitting it is a bad request rather than a silent publish."
          }
        }
      },
      "ThreadVisibilityUpdateResponse": {
        "type": "object",
        "required": [
          "thread"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "ThreadWorkspaceMoveRequest": {
        "type": "object",
        "required": [
          "workspace_channel_id"
        ],
        "properties": {
          "workspace_channel_id": {
            "type": "string",
            "pattern": "^ch_.+",
            "description": "Workspace channel to move the thread into."
          },
          "external_emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Current participants who are not workspace members and should stay on as external participants. Anyone omitted loses access to the thread."
          },
          "workspace_visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "default": "public",
            "description": "`public` announces the thread to the workspace; `private` announces it to nobody."
          }
        }
      },
      "ThreadWorkspaceMoveResponse": {
        "type": "object",
        "required": [
          "thread",
          "thread_in_channels"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "thread_in_channels": {
            "type": "array",
            "description": "The thread's new ownerless placement in the workspace channel.",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          }
        }
      },
      "ThreadUpdateRequest": {
        "type": "object",
        "required": [
          "thread"
        ],
        "properties": {
          "thread": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "ThreadSettingsUpdateRequest": {
        "type": "object",
        "required": [
          "settings"
        ],
        "properties": {
          "settings": {
            "type": "object",
            "minProperties": 1,
            "description": "Only the keys present are changed. See `ThreadSettings` for what each flag means. `is_sharing_enabled` mints or revokes the thread's share link; enabling it is rejected for a thread in a workspace.",
            "properties": {
              "is_sharing_enabled": {
                "type": "boolean"
              },
              "is_email_digests_disabled": {
                "type": "boolean"
              },
              "is_participant_notifications_disabled": {
                "type": "boolean"
              },
              "disable_participant_messaging": {
                "type": "boolean"
              },
              "disable_participant_sub_thread_messaging": {
                "type": "boolean"
              },
              "hide_participants": {
                "type": "boolean"
              },
              "participants_can_add_users": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "ThreadUpdateResponse": {
        "type": "object",
        "required": [
          "thread"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "ThreadDeleteResponse": {
        "type": "object",
        "required": [
          "thread_id",
          "deleted_at"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ThreadLeaveResponse": {
        "type": "object",
        "required": [
          "thread_id"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "preserve_thread": {
            "type": "boolean",
            "description": "Present and `true` when the thread stays browsable and can be rejoined."
          }
        }
      },
      "ThreadJoinRequest": {
        "type": "object",
        "properties": {
          "share_key": {
            "type": "string",
            "minLength": 1,
            "description": "Share key from the thread's share link. Omit the field entirely when joining a workspace thread or a sub-thread; an empty string is rejected."
          }
        }
      },
      "ThreadJoinResponse": {
        "type": "object",
        "required": [
          "thread"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          },
          "threads_in_channels": {
            "type": "array",
            "description": "The caller's placements for the joined thread.",
            "items": {
              "$ref": "#/components/schemas/ThreadInChannel"
            }
          }
        }
      },
      "ThreadUsersMutationResponse": {
        "type": "object",
        "required": [
          "thread"
        ],
        "properties": {
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        },
        "description": "Updated thread after user/role mutation."
      },
      "Icon": {
        "type": "object",
        "properties": {
          "color": {
            "$ref": "#/components/schemas/IconColor"
          },
          "emoji": {
            "$ref": "#/components/schemas/IconEmoji"
          }
        }
      },
      "ChannelIcon": {
        "type": "object",
        "description": "Optional channel icon metadata.",
        "properties": {
          "color": {
            "$ref": "#/components/schemas/IconColor"
          },
          "emoji": {
            "$ref": "#/components/schemas/IconEmoji"
          }
        }
      },
      "IconColor": {
        "type": "string",
        "enum": [
          "gray",
          "beige",
          "red",
          "aqua",
          "violet",
          "yellow",
          "mint",
          "silver",
          "pink",
          "blue",
          "green"
        ]
      },
      "IconEmoji": {
        "type": "string",
        "description": "A single Unicode emoji character, not a shortcode."
      },
      "Channel": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name",
          "role",
          "order",
          "deleted_at",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ch_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "channel"
            ]
          },
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "description": "Channel type (`personal`, `workspace`) or system bucket (`inbox`, `snoozed`, `archive`).",
            "enum": [
              "inbox",
              "snoozed",
              "archive",
              "personal",
              "workspace"
            ]
          },
          "order": {
            "type": "number",
            "description": "Sort order used by clients for channel listing."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "icon": {
            "$ref": "#/components/schemas/ChannelIcon"
          },
          "image": {
            "$ref": "#/components/schemas/ChannelImage"
          },
          "users": {
            "type": "array",
            "description": "Workspace members and their roles. Workspace channels only.",
            "items": {
              "$ref": "#/components/schemas/ChannelUser"
            }
          },
          "share_link": {
            "type": [
              "string",
              "null"
            ],
            "description": "Join link for the workspace, `null` when sharing is off. Workspace channels only."
          },
          "settings": {
            "$ref": "#/components/schemas/ChannelSettings"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "WorkspaceCreateRequest": {
        "type": "object",
        "required": [
          "channel",
          "member_emails"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/ChannelCreatePayload"
          },
          "member_emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Emails to add as members, `[]` for none. Unknown addresses are invited as new users."
          }
        }
      },
      "WorkspaceCreateResponse": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "notes": {
            "type": "string",
            "description": "Human-readable note naming any members left out, e.g. because they blocked the caller. Empty when everyone was added."
          }
        }
      },
      "WorkspaceSummary": {
        "type": "object",
        "description": "Minimal description of the workspace a thread lives in — enough to show where it belongs, with no roster and no member count. Carried by every participant's copy of the thread, external participants included, who are not workspace members and see nothing else about it.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ch_.+"
          },
          "name": {
            "type": "string"
          },
          "icon": {
            "$ref": "#/components/schemas/ChannelIcon"
          },
          "image": {
            "$ref": "#/components/schemas/ChannelImage"
          }
        }
      },
      "WorkspaceUpdateRequest": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "icon": {
                "$ref": "#/components/schemas/ChannelIcon"
              }
            }
          }
        }
      },
      "WorkspaceSettingsUpdateRequest": {
        "type": "object",
        "required": [
          "settings"
        ],
        "properties": {
          "settings": {
            "type": "object",
            "required": [
              "is_sharing_enabled"
            ],
            "properties": {
              "is_sharing_enabled": {
                "type": "boolean",
                "description": "Turns the join link on or off. Turning it off clears the key, so a link already shared stops working."
              }
            }
          }
        }
      },
      "WorkspaceChannelResponse": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          }
        }
      },
      "WorkspaceMembersAddRequest": {
        "type": "object",
        "required": [
          "member_emails"
        ],
        "properties": {
          "member_emails": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "Emails to add. Unknown addresses are invited as new users."
          }
        }
      },
      "WorkspaceUserIdsRequest": {
        "type": "object",
        "required": [
          "user_ids"
        ],
        "properties": {
          "user_ids": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^u_.+"
            }
          }
        }
      },
      "WorkspaceMembersResponse": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "notes": {
            "type": "string",
            "description": "Human-readable note naming anyone left out, e.g. because they blocked the caller. Empty when everyone was added."
          }
        }
      },
      "WorkspaceJoinRequest": {
        "type": "object",
        "required": [
          "share_key"
        ],
        "properties": {
          "share_key": {
            "type": "string",
            "description": "Share key from the workspace's join link."
          }
        }
      },
      "WorkspaceLeaveResponse": {
        "type": "object",
        "required": [
          "channel_id"
        ],
        "properties": {
          "channel_id": {
            "type": "string",
            "pattern": "^ch_.+"
          }
        }
      },
      "ChannelPreview": {
        "type": "object",
        "description": "Preview of the workspace behind a join link.",
        "required": [
          "id",
          "object",
          "name",
          "member_count"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ch_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "channel_preview"
            ]
          },
          "name": {
            "type": "string"
          },
          "member_count": {
            "type": "integer",
            "description": "How many members the workspace currently has."
          },
          "icon": {
            "$ref": "#/components/schemas/ChannelIcon"
          },
          "image": {
            "$ref": "#/components/schemas/ChannelImage"
          }
        }
      },
      "ChannelSettings": {
        "type": "object",
        "description": "Workspace channel settings.",
        "required": [
          "is_sharing_enabled"
        ],
        "properties": {
          "is_sharing_enabled": {
            "type": "boolean",
            "description": "Whether the join link is active. True exactly when `share_link` is set."
          }
        }
      },
      "ChannelUser": {
        "type": "object",
        "required": [
          "user_id",
          "roles"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "creator",
                "owner"
              ]
            }
          }
        }
      },
      "ChannelImage": {
        "type": "object",
        "description": "Uploaded image for the channel, present instead of `icon` when an image is set.",
        "properties": {
          "image_path": {
            "type": "string",
            "description": "First-party path to the encrypted small image; fetch and decrypt client-side with `encryption_key`."
          },
          "image_large_path": {
            "type": "string",
            "description": "First-party path to the encrypted large image."
          },
          "download_path": {
            "type": "string",
            "description": "API path to download the decrypted small image. GET it with your Bearer token and it redirects (302) to a signed media URL (see `downloadChannelImage`). The path contains the image key, which changes whenever the image changes, so responses are safe to cache."
          },
          "download_large_path": {
            "type": "string",
            "description": "API path to download the decrypted large image."
          },
          "encryption_key": {
            "type": "string",
            "description": "Base64-encoded AES-256-GCM key for decrypting the `*_path` images."
          }
        }
      },
      "ChannelImageUpload": {
        "type": "object",
        "required": [
          "image_file"
        ],
        "properties": {
          "image_file": {
            "type": "string",
            "format": "binary",
            "description": "Image file to set as the channel image."
          }
        }
      },
      "ChannelListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Channel"
                }
              }
            }
          }
        ]
      },
      "Integration": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name",
          "status",
          "type",
          "token_last_four",
          "webhook_url",
          "webhook_minor_version",
          "last_ip",
          "email",
          "last_used_at",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^int_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "integration"
            ]
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "revoked"
            ]
          },
          "type": {
            "type": "string",
            "description": "A personal token acting as the creator, or a bot with its own user.",
            "enum": [
              "personal_token",
              "bot"
            ]
          },
          "token_last_four": {
            "type": "string",
            "description": "Last four characters of the token, for identifying the credential."
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "webhook_minor_version": {
            "$ref": "#/components/schemas/WebhookMinorVersion"
          },
          "last_ip": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": "string",
            "description": "Email of the user the integration acts as."
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "supports": {
            "$ref": "#/components/schemas/BotSupports",
            "description": "Thread types other people may add this bot to. Present only for bots."
          },
          "profile": {
            "$ref": "#/components/schemas/UserProfile",
            "description": "The bot's card copy. Present only for bots that have any."
          },
          "avatar_small_path": {
            "type": "string",
            "description": "Relative path to the bot's small avatar. Present only for bots with an avatar."
          },
          "avatar_large_path": {
            "type": "string",
            "description": "Relative path to the bot's large avatar. Present only for bots with an avatar."
          }
        }
      },
      "WebhookMinorVersion": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}-\\d{2}$",
        "description": "API version webhook events are delivered at, as `X-Minor-Version` does\nfor requests. New integrations are pinned to the current version by\ndefault.\n"
      },
      "BotSupports": {
        "type": "array",
        "description": "Thread types other people may add this bot to; it can always start threads of its own,\nso an empty array means only the bot itself can.\n",
        "items": {
          "type": "string",
          "enum": [
            "one_on_one",
            "group"
          ]
        }
      },
      "IntegrationListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Integration"
                }
              }
            }
          }
        ]
      },
      "IntegrationResponse": {
        "type": "object",
        "required": [
          "integration"
        ],
        "properties": {
          "integration": {
            "$ref": "#/components/schemas/Integration"
          }
        }
      },
      "IntegrationCreatePayload": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Whether the integration acts as the creator or as its own bot user.",
            "enum": [
              "personal_token",
              "bot"
            ],
            "default": "personal_token"
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "webhook_minor_version": {
            "$ref": "#/components/schemas/WebhookMinorVersion"
          },
          "supports": {
            "$ref": "#/components/schemas/BotSupports"
          },
          "profile": {
            "$ref": "#/components/schemas/UserProfile"
          }
        }
      },
      "IntegrationCreateRequest": {
        "type": "object",
        "required": [
          "integration"
        ],
        "properties": {
          "integration": {
            "$ref": "#/components/schemas/IntegrationCreatePayload"
          }
        }
      },
      "IntegrationCreateResponse": {
        "type": "object",
        "required": [
          "integration",
          "token"
        ],
        "properties": {
          "integration": {
            "$ref": "#/components/schemas/Integration"
          },
          "token": {
            "type": "string",
            "description": "Plaintext token, returned only once at creation."
          },
          "webhook_signing_secret": {
            "type": "string",
            "description": "Webhook signing secret, returned only once when a webhook_url is set."
          }
        }
      },
      "IntegrationUpdatePayload": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "webhook_minor_version": {
            "$ref": "#/components/schemas/WebhookMinorVersion"
          },
          "supports": {
            "$ref": "#/components/schemas/BotSupports"
          },
          "profile": {
            "$ref": "#/components/schemas/UserProfile"
          }
        }
      },
      "IntegrationUpdateRequest": {
        "type": "object",
        "required": [
          "integration"
        ],
        "properties": {
          "integration": {
            "$ref": "#/components/schemas/IntegrationUpdatePayload"
          }
        }
      },
      "IntegrationUpdateResponse": {
        "type": "object",
        "required": [
          "integration"
        ],
        "properties": {
          "integration": {
            "$ref": "#/components/schemas/Integration"
          },
          "webhook_signing_secret": {
            "type": "string",
            "description": "Webhook signing secret, returned only when a webhook_url is first set."
          }
        }
      },
      "IntegrationAvatarUpload": {
        "type": "object",
        "required": [
          "avatar_file"
        ],
        "properties": {
          "avatar_file": {
            "type": "string",
            "format": "binary",
            "description": "Image file to use as the bot avatar."
          }
        }
      },
      "ThreadImageUpload": {
        "type": "object",
        "required": [
          "image_file"
        ],
        "properties": {
          "image_file": {
            "type": "string",
            "format": "binary",
            "description": "Image file to set as the thread image."
          }
        }
      },
      "ThreadImage": {
        "type": "object",
        "description": "The thread's icon or uploaded image. Either `icon` is set (a `{ color, emoji }` icon), or the image fields are set.",
        "properties": {
          "icon": {
            "$ref": "#/components/schemas/Icon"
          },
          "image_path": {
            "type": "string",
            "description": "First-party path to the encrypted small image; fetch and decrypt client-side with `encryption_key`."
          },
          "image_large_path": {
            "type": "string",
            "description": "First-party path to the encrypted large image."
          },
          "download_path": {
            "type": "string",
            "description": "API path to download the decrypted small image. GET it with your Bearer token and it redirects (302) to a signed media URL (see `downloadThreadImage`). The path contains the image key, which changes whenever the image changes, so responses are safe to cache."
          },
          "download_large_path": {
            "type": "string",
            "description": "API path to download the decrypted large image."
          },
          "encryption_key": {
            "type": "string",
            "description": "Base64-encoded AES-256-GCM key for decrypting the `*_path` images."
          }
        }
      },
      "ChannelCreatePayload": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "order": {
            "type": "number"
          },
          "icon": {
            "$ref": "#/components/schemas/ChannelIcon"
          }
        }
      },
      "ChannelUpdatePayload": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "order": {
            "type": "number"
          },
          "icon": {
            "$ref": "#/components/schemas/ChannelIcon"
          }
        }
      },
      "ChannelCreateRequest": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/ChannelCreatePayload"
          }
        }
      },
      "ChannelUpdateRequest": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/ChannelUpdatePayload"
          }
        }
      },
      "ChannelCreateResponse": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          }
        }
      },
      "ChannelUpdateResponse": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          }
        }
      },
      "ChannelDeleteResponse": {
        "type": "object",
        "required": [
          "channel_id",
          "deleted_at"
        ],
        "properties": {
          "channel_id": {
            "type": "string",
            "pattern": "^ch_.+"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ScheduledMessageContent": {
        "type": "object",
        "required": [
          "id",
          "body"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "body": {
            "type": "string"
          },
          "reply_to": {
            "type": "string",
            "pattern": "^m_.+"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageAttachment"
            }
          }
        }
      },
      "ScheduledMessage": {
        "type": "object",
        "required": [
          "id",
          "object",
          "thread_id",
          "user_id",
          "scheduled_at",
          "created_at",
          "updated_at",
          "message"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sm_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "scheduled_message"
            ]
          },
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "message": {
            "$ref": "#/components/schemas/ScheduledMessageContent"
          }
        }
      },
      "ScheduledMessageCreateRequest": {
        "type": "object",
        "required": [
          "thread_id",
          "scheduled_at",
          "message"
        ],
        "properties": {
          "thread_id": {
            "type": "string",
            "pattern": "^th_.+"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Must be at least 1 minute in the future."
          },
          "message": {
            "type": "object",
            "description": "`body` is required unless `attachments` are provided.\n",
            "properties": {
              "body": {
                "type": "string"
              },
              "reply_to": {
                "type": "string",
                "pattern": "^m_.+",
                "description": "Prefixed message id to reply to."
              },
              "attributes": {
                "type": "object",
                "additionalProperties": true
              },
              "attachments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^att_.+"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ScheduledMessageUpdateRequest": {
        "type": "object",
        "description": "At least one of `scheduled_at` or `message` must be provided.",
        "properties": {
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Must be at least 1 minute in the future."
          },
          "message": {
            "type": "object",
            "properties": {
              "body": {
                "type": "string"
              },
              "reply_to": {
                "type": "string",
                "pattern": "^m_.+"
              },
              "attributes": {
                "type": "object",
                "additionalProperties": true
              },
              "attachments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^att_.+"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ScheduledMessageResponse": {
        "type": "object",
        "required": [
          "scheduled_message"
        ],
        "properties": {
          "scheduled_message": {
            "$ref": "#/components/schemas/ScheduledMessage"
          }
        }
      },
      "ScheduledMessageListResponse": {
        "type": "object",
        "required": [
          "scheduled_messages"
        ],
        "properties": {
          "scheduled_messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScheduledMessage"
            }
          }
        }
      },
      "ScheduledMessageDeleteResponse": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sm_.+"
          }
        }
      },
      "ScheduledMessageSendResponse": {
        "type": "object",
        "required": [
          "id",
          "message",
          "thread"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sm_.+"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "thread": {
            "$ref": "#/components/schemas/Thread"
          }
        }
      },
      "Attachment": {
        "type": "object",
        "required": [
          "id",
          "object",
          "type",
          "key",
          "status",
          "user_id",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^att_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "attachment"
            ]
          },
          "type": {
            "type": "string"
          },
          "filename": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "key": {
            "type": "string"
          },
          "preview_key": {
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "finished"
            ]
          },
          "user_id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "thread_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^th_.+"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^m_.+"
          },
          "width": {
            "type": [
              "integer",
              "null"
            ]
          },
          "height": {
            "type": [
              "integer",
              "null"
            ]
          },
          "preview_size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "preview_width": {
            "type": [
              "integer",
              "null"
            ]
          },
          "preview_height": {
            "type": [
              "integer",
              "null"
            ]
          },
          "preview_status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "pending",
              "finished",
              null
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "AttachmentCreateRequest": {
        "description": "Attachment create request, accepts flat or nested payload shape.",
        "oneOf": [
          {
            "type": "object",
            "required": [
              "filename",
              "size"
            ],
            "properties": {
              "filename": {
                "type": "string",
                "description": "Original filename presented to Balsio users."
              },
              "content_type": {
                "type": "string",
                "description": "MIME type of the uploaded file, for example `application/pdf`."
              },
              "size": {
                "type": "integer",
                "description": "Size of the original uploaded file in bytes."
              },
              "thread_id": {
                "type": "string",
                "pattern": "^th_.+",
                "description": "Optional thread to associate with the attachment metadata."
              },
              "preview_size": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Optional preview object size in bytes, if a preview will also be uploaded."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "attachment"
            ],
            "properties": {
              "attachment": {
                "type": "object",
                "required": [
                  "filename",
                  "size"
                ],
                "properties": {
                  "filename": {
                    "type": "string",
                    "description": "Original filename presented to Balsio users."
                  },
                  "content_type": {
                    "type": "string",
                    "description": "MIME type of the uploaded file, for example `application/pdf`."
                  },
                  "size": {
                    "type": "integer",
                    "description": "Size of the original uploaded file in bytes."
                  },
                  "thread_id": {
                    "type": "string",
                    "pattern": "^th_.+",
                    "description": "Optional thread to associate with the attachment metadata."
                  },
                  "preview_size": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Optional preview object size in bytes, if a preview will also be uploaded."
                  }
                }
              }
            }
          }
        ]
      },
      "AttachmentCreatePayload": {
        "type": "object",
        "required": [
          "id",
          "upload_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^att_.+"
          },
          "upload_url": {
            "type": "string",
            "format": "uri",
            "description": "Signed URL to upload the file to. POST the file as multipart/form-data\nwith a `file` field. Maximum file size is 10 MB.\n"
          }
        }
      },
      "AttachmentCreateResponse": {
        "type": "object",
        "required": [
          "attachment"
        ],
        "properties": {
          "attachment": {
            "$ref": "#/components/schemas/AttachmentCreatePayload"
          }
        }
      },
      "AttachmentDeleteResponse": {
        "type": "object",
        "required": [
          "attachment_id"
        ],
        "properties": {
          "attachment_id": {
            "type": "string",
            "pattern": "^att_.+"
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "company": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "about_me": {
            "type": "string"
          },
          "links": {
            "type": "object",
            "description": "Links the profile publishes. Omitted when there are none. Keys are a closed set,\nso render the ones you know and ignore the rest.\n",
            "properties": {
              "terms": {
                "type": "string"
              },
              "privacy_policy": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "User": {
        "type": "object",
        "required": [
          "id",
          "object",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^u_.+"
          },
          "object": {
            "type": "string",
            "enum": [
              "user"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "name": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "time_zone": {
            "type": [
              "string",
              "null"
            ]
          },
          "avatar_small_path": {
            "type": "string"
          },
          "avatar_small_url": {
            "type": "string"
          },
          "avatar_large_path": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "bot"
              ]
            },
            "description": "Public roles assigned to this user. Only present when the user has at least one public role."
          },
          "account_status": {
            "type": "string",
            "enum": [
              "suspended",
              "deleted"
            ],
            "description": "Present only when the account is not in normal standing. A `suspended` account is shown to others under a placeholder `name` and `display_name`, without email, avatars, profile, time zone, or WhatsApp JID; clients may replace the placeholder with a localized label or a badge. A `deleted` account has been anonymized."
          },
          "profile": {
            "$ref": "#/components/schemas/UserProfile"
          },
          "whatsapp_jid": {
            "type": "string",
            "maxLength": 255,
            "description": "The user's WhatsApp interoperability JID. Present only when the user has enabled WhatsApp interoperability."
          }
        }
      },
      "UserListResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": [
          "type",
          "code",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "example": "invalid_request_error"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.\nExamples of currently documented values include `forbidden`,\n`invalid_channel_id`, `invalid_json`, `invalid_message`, `invalid_message_id`,\n`invalid_params`, `invalid_scheduled_at`, `invalid_scheduled_message_id`,\n`invalid_thread_id`, `limit_exceeded`, `missing_message`, `missing_thread_id`,\n`not_authenticated`, `not_found`, and `permission_denied`.\n",
            "example": "missing_message_id"
          },
          "message": {
            "type": "string",
            "example": "The message_id parameter is required and must be m_ prefixed"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "ErrorTopLevel": {
        "type": "object",
        "required": [
          "type",
          "code",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "example": "invalid_request_error"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.\nExamples of currently documented values include `forbidden`,\n`invalid_channel_id`, `invalid_json`, `invalid_message`, `invalid_message_id`,\n`invalid_params`, `invalid_scheduled_at`, `invalid_scheduled_message_id`,\n`invalid_thread_id`, `limit_exceeded`, `missing_message`, `missing_thread_id`,\n`not_authenticated`, `not_found`, and `permission_denied`.\n",
            "example": "not_authenticated"
          },
          "message": {
            "type": "string",
            "example": "Request is not authenticated"
          }
        }
      },
      "MessageOnlyError": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "example": "Not found"
          }
        }
      },
      "InvalidJsonError": {
        "type": "object",
        "required": [
          "success",
          "object",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "object": {
            "type": "string",
            "const": "error"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "const": "invalid_json"
              },
              "message": {
                "type": "string",
                "example": "Malformed JSON request body"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "description": "API currently returns multiple error payload shapes.\nMost endpoints use `error` envelope payloads, auth failures use top-level\n`type/code/message`, and some legacy paths return a top-level `message`.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ErrorEnvelope"
          },
          {
            "$ref": "#/components/schemas/ErrorTopLevel"
          },
          {
            "$ref": "#/components/schemas/MessageOnlyError"
          },
          {
            "$ref": "#/components/schemas/InvalidJsonError"
          }
        ]
      },
      "ListMeta": {
        "type": "object",
        "required": [
          "object",
          "has_more"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "prev_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "responses": {
      "Forbidden": {
        "description": "Request is authenticated but not allowed for this resource (permission or mutability constraint).",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "forbidden": {
                "value": {
                  "error": {
                    "type": "invalid_request_error",
                    "code": "forbidden",
                    "message": "Request is not allowed for this resource"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource is not found or not visible in current scope.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "value": {
                  "error": {
                    "type": "invalid_request_error",
                    "code": "not_found",
                    "message": "Resource not found"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Request is not authenticated.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notAuthenticated": {
                "value": {
                  "type": "invalid_request_error",
                  "code": "not_authenticated",
                  "message": "Request is not authenticated"
                }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Bad request payload or malformed JSON.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidJson": {
                "value": {
                  "success": false,
                  "object": "error",
                  "error": {
                    "code": "invalid_json",
                    "message": "Malformed JSON request body"
                  }
                }
              }
            }
          }
        }
      },
      "RateLimit": {
        "description": "Request was rate limited.",
        "headers": {
          "retry-after": {
            "description": "Seconds to wait before retrying the request.",
            "schema": {
              "type": "integer"
            }
          },
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "limitExceeded": {
                "value": {
                  "error": {
                    "type": "rate_limit",
                    "code": "limit_exceeded",
                    "message": "Rate limit exceeded"
                  }
                }
              },
              "requestLimitExceeded": {
                "value": {
                  "error": {
                    "type": "rate_limit",
                    "code": "rate_limit_exceeded",
                    "message": "Too many requests"
                  }
                }
              }
            }
          }
        }
      },
      "NotFoundMessageOnly": {
        "description": "Requested resource is not found.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/MessageOnlyError"
            },
            "examples": {
              "notFound": {
                "value": {
                  "message": "Not found"
                }
              }
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Validation failed for the request payload.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidPayload": {
                "value": {
                  "error": {
                    "message": "Validation failed"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Core Messaging",
      "tags": [
        "Threads",
        "Messages",
        "Scheduled Messages",
        "Channels",
        "Users",
        "Events"
      ]
    },
    {
      "name": "File Handling",
      "tags": [
        "Attachments"
      ]
    },
    {
      "name": "Integrations & Webhooks",
      "tags": [
        "Integrations",
        "Webhooks"
      ]
    }
  ]
}