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"
}
}Codes are not a fixed enum. Most errors return HTTP 400 with either an ERR_-prefixed code (e.g. ERR_VALIDATION, ERR_GENERIC) or a specific service code (e.g. POST_NOT_FOUND, USER_NOT_FOUND, EMAIL_INVALID). Treat code as a string to map to a localized message rather than relying on a closed list.
Pagination
List endpoints accept page (1-indexed) and pageSize (default varies by endpoint, commonly 20; max 100). Responses include { data, page, pageSize, total }.