Skip to main content
Every API response follows one of three shapes. Check the success field first to determine how to read the rest.

​
Success Response

Returned when the request completes successfully. 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example University",
    "slug": "example-u"
  },
  "message": "Tenant created successfully"
}
FieldTypeDescription
successbooleanAlways true
dataobject | nullThe response payload. null for operations with no return value (e.g. delete).
messagestring | nullOptional human-readable message

​
Error Response

Returned when the request fails for any reason — validation, auth, server error, etc. 
{
  "success": false,
  "error": "Tenant 'abc123' not found",
  "code": "NOT_FOUND",
  "details": {}
}
FieldTypeDescription
successbooleanAlways false
errorstringHuman-readable error message
codestringMachine-readable error code (see Error Codes)
detailsobjectAdditional context. Empty {} when not applicable. For validation errors, contains field-level messages.

​
Validation Error Example

When request body validation fails, details contains a map of field names to error messages: 
{
  "success": false,
  "error": "Request validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "email": "value is not a valid email address",
    "name": "field required"
  }
}

​
Paginated Response

Returned for list endpoints that support pagination. 
{
  "success": true,
  "data": [
    { "id": "...", "name": "..." },
    { "id": "...", "name": "..." }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "message": null
}
FieldTypeDescription
successbooleanAlways true
dataarrayThe list of items for the current page
totalintegerTotal number of items across all pages
pageintegerCurrent page number (1-indexed)
page_sizeintegerNumber of items per page
total_pagesintegerTotal number of pages
messagestring | nullOptional message
See Pagination for query parameter details.

​
Frontend Handling

interface APISuccess<T> {
  success: true;
  data: T;
  message: string | null;
}

interface APIError {
  success: false;
  error: string;
  code: string;
  details: Record<string, string>;
}

interface APIPaginated<T> {
  success: true;
  data: T[];
  total: number;
  page: number;
  page_size: number;
  total_pages: number;
  message: string | null;
}

type APIResponse<T> = APISuccess<T> | APIError;