Responses and conventions

This section covers the baseline behaviour across all API endpoints, including response shapes, error handling, and status codes.

Response formats

All API responses are returned in JSON format.

Successful requests return a 2xx status code. List endpoints return a consistent paginated shape:

{
    "results": [],
    "count": 0
}

Individual resource endpoints (GET, POST, PATCH) return the resource object directly:

{
    "id": 123,
    "title": "Example resource",
    ...
}

When a request fails, the API returns a 4xx or 5xx status code along with a JSON body explaining the error.

These errors return a simple message in the detail field:

{
    "detail": "Invalid API key."
}

Validation errors can be field-specific:

{
    "board_id": ["This field is required."],
    "title": ["This field may not be blank."]
}

Or a general error message:

{
    "detail": "This board does not allow new posts."
}

Scalar uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Meaning
200 - OK	Everything worked as expected.
201 - Created	The resource was successfully created.
204 - No Content	The request was successful (usually for DELETE) and there is no response body.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter or validation error.
401 - Unauthorized	No valid API key provided.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
429 - Too Many Requests	Too many requests hit the API too quickly. See Rate limiting.
500, 502, 503, 504 - Server Errors	Something went wrong on Scalar's end.

Company-scoped: The API key identifies exactly one company; all queries are automatically scoped to that company.
Soft deletes: The API only exposes active resources (is_active=true).
System actor: Requests authenticate as a company, not a specific person. For actions that require an author (like creating an idea), the system assigns the earliest-created active ADMIN user.