Developer Overview
Sosyabot exposes a REST API at <BASE_URL>/api/v1/*. Most endpoints require a session cookie issued by the dashboard sign-in flow; a small subset accepts a personal API token via the Authorization header.
Authentication
| Endpoint family | Auth |
|---|---|
/api/v1/* (default) | Session cookie (token, httpOnly, set on sign-in / OTP verify). |
/api/v1/public/* | API token via Authorization: Bearer <token> header, with explicit scopes. |
/api/v1/auth/* | None (sign-in / signup / OAuth callbacks). |
/api/v1/webhooks/* | None for inbound (signed by the provider); outbound bound by the registered webhook secret. |
Errors
Errors use a consistent envelope:
json
{
"error": {
"code": "POST_NOT_FOUND",
"message": "Post does not exist"
}
}Common codes: VALIDATION_ERROR (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500).
Pagination
List endpoints accept page (1-indexed) and pageSize (default 25, max 100). Responses include { data, page, pageSize, total }.