# BirdyChat Integrations API

> BirdyChat is a team messaging platform. This site documents the public integrations API, the events WebSocket, and the MCP surface.

## Canonical Sources

- API Reference: https://docs.birdy.chat/
- OpenAPI JSON: https://docs.birdy.chat/openapi.json
- OpenAPI YAML: https://docs.birdy.chat/openapi.yaml
- Events WebSocket Docs: https://docs.birdy.chat/events-socket.html
- Events WebSocket Markdown: https://docs.birdy.chat/events-socket.md
- Events WebSocket AsyncAPI JSON: https://docs.birdy.chat/events-socket.asyncapi.json
- Events WebSocket AsyncAPI YAML: https://docs.birdy.chat/events-socket.asyncapi.yaml
- MCP Docs: https://docs.birdy.chat/mcp.html
- MCP Markdown: https://docs.birdy.chat/mcp.md

## Quick Notes

- Base URL: `https://birdy.chat/api/v1`
- Events WebSocket: `wss://birdy.chat/api/v1/events/socket`
- Auth: `Authorization: Bearer sk_...` (same for REST, WebSocket, and MCP)
- Request and response bodies use JSON
- Pagination is cursor-based; see the OpenAPI docs for endpoint-specific params and cursors
- Error response shapes vary by endpoint; see the OpenAPI docs for the canonical contract
- For machine-readable REST API details, prefer the OpenAPI JSON or YAML above
- For machine-readable WebSocket details, prefer the AsyncAPI JSON or YAML above

## ID Prefixes

All resource IDs are prefixed strings: threads `th_`, messages `m_`, channels `ch_`, users `u_`, attachments `att_`, REST events `e_`, webhook events `evt_`.

## Guidance For LLMs

- Treat the OpenAPI JSON/YAML as the canonical REST API contract
- Treat the AsyncAPI JSON/YAML as the canonical WebSocket contract; the `Event` schema is shared with the REST `/events` endpoint
- Use the MCP docs for tool-oriented assistant integrations
- Do not infer undocumented fields or writable server-managed timestamps