API Overview
The Zlikord API is a REST API served over HTTP with WebSocket support for real-time events.
Base URL
Section titled “Base URL”http://<your-tailscale-ip>:8787/api/v1Authentication
Section titled “Authentication”Most endpoints require a JWT Bearer token in the Authorization header:
Authorization: Bearer <token>Obtain a token by calling POST /api/v1/auth/login.
Health Check
Section titled “Health Check”GET /healthReturns 200 OK with {"status":"ok"}. No authentication required.
Pagination
Section titled “Pagination”Message endpoints use cursor-based pagination:
before— Message ID. Returns messages older than this ID.limit— Number of messages to return (default varies by endpoint).
Example:
GET /api/v1/channels/42/messages?limit=50&before=1000Rate Limiting
Section titled “Rate Limiting”Message creation endpoints are rate-limited using a token bucket algorithm. Defaults:
- Burst: 5 messages
- Refill: 1 token per second
Configurable via MESSAGE_RATE_BURST and MESSAGE_RATE_REFILL_PER_SEC environment variables.
Error Responses
Section titled “Error Responses”Errors return a JSON object with a message:
{ "error": "description of what went wrong"}Common HTTP status codes:
| Status | Meaning |
|---|---|
400 | Bad request (invalid input) |
401 | Unauthorized (missing or invalid token) |
403 | Forbidden (insufficient permissions) |
404 | Not found |
405 | Method not allowed |
429 | Rate limited |
500 | Internal server error |