# Zynko API > The HTTP API of Zynko (https://zynko.org), a Brazilian chat app: servers (called guilds in the API) with text channels, forums and voice rooms, direct messages, friends and bots. JSON over HTTPS, plus a WebSocket gateway for real-time events. - Base URL: https://zynko.org/api/v1 (the unversioned https://zynko.org/api is the same version 1, used by Zynko's own apps). - IDs are 64-bit snowflakes sent as strings. Dates are Unix milliseconds. - Errors are JSON `{"code": "...", "message": "..."}`; messages are in Portuguese, codes are stable. - Zynko looks like Discord but is not Discord: don't use Discord libraries, routes, opcodes, intents or permission bits. ## Authentication - OAuth 2.1 for apps and AI agents acting for a person: authorization code with PKCE (S256), public clients registered dynamically (RFC 7591) or identified by a Client ID Metadata Document URL. Scopes: `user:read`, `servers:read`, `servers:join`, `messages:read`, `messages:write`, `friends:read`. Agents without a browser can register a `service_auth` identity that the person approves with a one-time code. Walkthrough: https://zynko.org/auth.md - Bot tokens for bots: `Authorization: Bot bot_<64 hex>`, created at https://dev.zynko.org. - A request without valid credentials gets 401 with `WWW-Authenticate: Bearer resource_metadata="https://zynko.org/.well-known/oauth-protected-resource/api"`. An OAuth token without the scope a route needs gets 403 `insufficient_scope`. ## Discovery - [OpenAPI 3.1 description](https://zynko.org/openapi.json): every operation, its scopes and its schemas. - [Authorization server metadata](https://zynko.org/.well-known/oauth-authorization-server) - [Protected resource metadata](https://zynko.org/.well-known/oauth-protected-resource/api) - [API catalog (RFC 9727)](https://zynko.org/.well-known/api-catalog) ## MCP servers - Zynko MCP, endpoint https://zynko.org/mcp (Streamable HTTP): community search works without a token; tools on the person's servers, channels and messages ask for OAuth sign-in. [Server card](https://zynko.org/mcp/server-card) - Zynko Docs MCP, endpoint https://docs.zynko.org/mcp (public): search and read the documentation. [Server card](https://docs.zynko.org/mcp/server-card) - Local server for bot developers: `npx -y zynko-mcp` (documentation and tests with a bot token). ## Conventions - Rate limits: every response carries `RateLimit-Policy` and `RateLimit` (1200 requests per 60 s per token, 300 per 60 s per address without one; a token the API turns down with 401 also counts against the address). A 429 carries `Retry-After` and `retry_after_ms`. Some actions have tighter limits (for example 10 messages per 10 s per bot). - Idempotency: writes accept an `Idempotency-Key` header; a retry with the same key and body within 24 hours gets the first answer again (`Idempotent-Replayed: true`). The OAuth and agent endpoints (`/oauth/*`, `/agent/*`) are never replayed: their codes and claim tokens are single use. - Pagination: messages take `limit` and `before` (alias `cursor`) = the id of the oldest message you have; forum posts take `before`/`cursor` = the sort key of the last post you got (its `last_message_id`, or its `id` when it has none or with sort=created). - Data export: `POST /users/@me/exports` answers 202 with a `Location` to poll (session tokens only); a new export replaces the previous one. - Real-time events: WebSocket gateway at wss://zynko.org/api/v1/gateway (bot and session tokens). ## Docs (Markdown, in Portuguese) - [API overview](https://docs.zynko.org/api/index.md) - [Routes](https://docs.zynko.org/api/rotas.md) - [Objects](https://docs.zynko.org/api/objetos.md) - [Gateway](https://docs.zynko.org/api/gateway.md) - [Events](https://docs.zynko.org/api/eventos.md) - [Permissions](https://docs.zynko.org/api/permissoes.md) - [OAuth](https://docs.zynko.org/api/oauth.md) ## Optional - [Zynko for AI agents](https://zynko.org/agents.md) - [Site index](https://zynko.org/llms.txt) - [Documentation index](https://docs.zynko.org/llms.txt)