API Reference

Every Apso service generates a REST API from your schema using the CRUD framework (@apso/crud, nestjsx/crud conventions). Each entity gets standard CRUD endpoints plus a rich query string for filtering, sorting, joining, and pagination. This page documents that query contract — the same one the SDK builds.

Authentication

Programmatic access uses a service API key (apso_…) sent as a header. Create and manage keys in API Key Management.


curl https://<your-service>.apso.cloud/Products \
  -H "Authorization: Bearer apso_your_key_here"

OAuth2 in Apso is the platform/app login (BetterAuth providers — GitHub, Google, etc.) used to sign in to the dashboard. It is not a per-request flow for the generated data API; the data API is authenticated with a service API key (or the auth your generated service configures). There is no separate OAuth2 client-credentials flow for the CRUD endpoints.

Endpoints

For an entity Product:

Method	Path	Purpose
`GET`	`/Products`	List (with query below)
`GET`	`/Products/:id`	Get one
`POST`	`/Products`	Create
`PATCH`	`/Products/:id`	Update
`PUT`	`/Products/:id`	Replace
`DELETE`	`/Products/:id`	Delete
`POST`	`/Products/bulk`	Bulk create

Filtering

Each filter is filter[n]=field||$operator||value:


GET /Products?filter[0]=status||$eq||active&filter[1]=price||$gt||100

Common operators (nestjsx/crud set):

Operator	Meaning
`$eq` / `$ne`	equals / not equals
`$gt` / `$lt` / `$gte` / `$lte`	greater/less than (or equal)
`$cont` / `$starts` / `$ends`	contains / starts-with / ends-with
`$in` / `$notin`	in / not in a list
`$between`	within a range
`$isnull` / `$notnull`	null / not null

Case-insensitive variants exist for text operators ($contL, $inL, $notinL, …). Combine alternatives with $or.

Sorting

sort[n]=field,DIRECTION:


GET /Products?sort[0]=created_at,DESC&sort[1]=name,ASC

Joining relations

join[n]=relation (optionally select fields):


GET /Products?join[0]=category&join[1]=reviews||rating,comment

Field selection

fields= limits the returned columns:


GET /Products?fields=id,name,price

Pagination

Use limit with page (or offset):


GET /Products?limit=20&page=2

A list response is paginated:


{
  "data": [ /* records */ ],
  "count": 20,
  "total": 137,
  "page": 2,
  "pageCount": 7
}

count — items in this page
total — items matching the query
page / pageCount — current page and total pages

Error responses

Errors follow the standard envelope ({ statusCode, message, error }); malformed ids and unknown query fields return 400, auth failures 401, and quota 429. See Error Handling for the full catalog and examples.

Not part of the generated API

Some items commonly expected in an “API reference” are not part of the generated CRUD API today:

Explicit API versioning — routes are unversioned; there is no /v1 prefix or deprecation channel on the generated endpoints.
Webhooks — the CRUD API does not emit webhooks. (Domain-event emission is a separate, opt-in mechanism configured on the service, not a webhook subscription API.)
Server-side rate-limit configuration per key — throttling is handled at the deployment/tier level, not configured per API key.

Document these as they land rather than describing them as available.

SDK — a typed client that builds these queries for you
API Key Management · Error Handling