API basics

The base URL, versioning and the common response format of the AISAR API: the data envelope, pagination, errors and 204.

This guide describes the common conventions of the AISAR API: the base URL and versioning, and the uniform format the API uses to return data — the data envelope, pagination, errors and empty responses. These conventions are the same across every endpoint group in the REST reference.

Base URL

The AISAR API is hosted on a dedicated subdomain. All public REST API requests go to the base URL with the /v1 version prefix (there is no intermediate /api segment):

text

https://api.aisar.app/v1

The version number is part of the path (/v1). This is the current and only API version; if breaking changes are ever introduced they will ship under a new version prefix while /v1 keeps working.

Besides the public /v1 surface, the platform uses a separate internal service-to-service surface for its runtime services to talk to the core. It is not part of the public integration surface and is not documented in this reference.

Single-object response

Successful responses that return a single resource wrap it in a data field:

json

{
  "data": { "...": "..." }
}

List response

Non-paginated list responses return an array in the same data field:

json

{
  "data": [{ "...": "..." }]
}

Paginated list

Paginated lists return, inside data, an object with an items array and a pagination object. Page size is set with the perPage query parameter (20 by default for most groups) and the page number with page:

json

{
  "data": {
    "items": [{ "...": "..." }],
    "pagination": {
      "page": 1,
      "perPage": 20,
      "total": 150,
      "lastPage": 8
    }
  }
}

Field	Description
`page`	The current page number.
`perPage`	The number of items per page.
`total`	The total number of items across all pages.
`lastPage`	The number of the last page.

Error envelope

Errors are not wrapped in data. Every error response carries a top-level message field with a human-readable description:

json

{
  "message": "Not found"
}

The full status-code table (401/403/404/422/429/5xx), a plan feature-gate error example and retry recommendations live in the Errors guide.

204 No Content

Actions with nothing to return (for example deleting a resource) respond with 204 No Content and an empty body. Do not try to parse the body of such responses as JSON.