The application API reads and changes PostgreSQL records. Distinguish it from the local generator API, which edits the model. Routes depend on modules, entity names, operations and access; consult your project's OpenAPI.
Preparing the API in the UI
- In Content → entity → settings → Access, select operations and external access. Set mandatory read conditions under External READ access.
- Enable required Searchable, Filterable, Sortable under Advanced settings → List behavior. Configure virtual relationship/collection selections separately.
- Inspect routes under Access → Generated routes.
- Generate → Preview changes → Generate, then start the backend with updated code.
The examples below are for integration developers. Use the admin for regular data entry; manual HTTP requests are unnecessary.
Admin and external routes
For module content and entity route articles, there are two base addresses:
/api/admin/v1/content/articles
/api/external/v1/content/articles
| Method | Path relative to base | Purpose |
|---|---|---|
GET |
Base path | Return a list. |
GET |
/{id} |
Return one record. |
POST |
Base path | Create a record. |
PATCH |
/{id} |
Update under the object contract. |
DELETE |
/{id} |
Delete a record. |
Admin API requires the relevant permissions. Each external operation selects off, authenticated or anonymous: disabled, sign-in required or anonymous requests allowed. Read permission does not enable writes.
PATCH does not automatically merge arbitrary fields into a record. Send the object according to its documented contract and preserve current model fields.
Pagination, search and filters
Lists return {items, total, limit, offset}. A page contains at most 100 records; clients request subsequent pages to continue.
Use only fields with enabled search, filter and sort capabilities:
| Parameter | Contents |
|---|---|
searches |
JSON array of field/value conditions. |
filters |
field/op/value conditions. |
sort, order |
Sort field and direction. |
For example, filtering slug or status requires Filterable. The server validates field names and passes values as SQL parameters.
Terminal request:
curl --fail --get \
--data-urlencode 'limit=20' --data-urlencode 'offset=0' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
http://127.0.0.1:8081/api/admin/v1/content/articles
ACCESS_TOKEN must contain an existing session token. Substitute your address and route. Do not save admin tokens in website files. For visitors, use external APIs with read rules.
Related records
These suffixes extend the entity base address:
| Suffix | Action |
|---|---|
/relations/{relation}/options |
GET: bounded selection list. |
/relations/{relation}/options/{targetId} |
GET: selected-record label and data. |
/{sourceId}/relations/{relation} |
GET: related records. |
/{sourceId}/relations/{relation}/{targetId} |
POST/DELETE: owner-side manyToMany membership changes. |
Reads check access to source and target entities. Membership changes require owner and target permissions. Virtual entities are read-only, with separate OpenAPI response schemas.
Images
Admin operations are under /api/admin/v1/_media/{entity}/{field}: POST /uploads, GET /{assetId}, GET /{assetId}/files/{variant}, POST /{assetId}/process. They check access, file size and processing state. A JSON reference does not allow anonymous private upload/processing access.
External responses contain a size map of variant URLs. This differs from the admin media contract.
Mandatory read rules
External list/get conditions apply before pagination and total counting. A record denied by its rule yields 404 from get. Rules support AND/OR, scalar fields and one belongsTo hop. Virtual collections have separate rules and parameters; see projections.
OpenAPI and errors
OpenAPI describes persistent/virtual responses: fields, types, nullable and enum. Write objects are separate from responses. Use these schemas to build a client.
Check HTTP status and structured errors. Request IDs help find log events. An empty result does not prove deletion; a network error does not prove absence. Accounts and sessions are in authentication.
Configure response contents in fields and virtual entities; routes and mandatory conditions in Access.