Application API: records, relationships and images

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

1. In Content → entity → settings → Access, select operations and external access. Set mandatory read conditions under External READ access.
2. Enable required Searchable, Filterable, Sortable under Advanced settings → List behavior. Configure virtual relationship/collection selections separately.
3. Inspect routes under Access → Generated routes.
4. 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

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:

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.

Response language and translation updates

First configure languages and translated fields in Entity settings → Languages, Generate, apply migrations and update the application. locale selects content language, not interface language. It applies to list/get, search, filters, sorting and selected virtual fields, including nested collections.

For example, request a Product in module catalog with numeric ID 1:

curl --fail 'http://127.0.0.1:8081/api/external/v1/catalog/products/1?locale=ru'

This assumes external get allows anonymous access. Substitute your host, module, route and ID; an authenticated request also needs a token. Selecting a language does not grant access to the record.

An example response with a completed translation:

{
  "id": 1,
  "name": "Кружка",
  "description": "Керамическая кружка.",
  "price": 1490,
  "categoryId": 2
}

The properties remain name and description, not name-ru or description-ru; suffixes appear only in form labels. Without locale, each source uses its own default language. If a persistent entity has content languages enabled, requesting a language outside its configured list returns HTTP 400. A virtual entity accepts the combined languages of its selected translated fields.

Missing values follow the field owner's Missing translation setting: null, or that field's default-language value. Fallback applies per field. A related entity with different languages follows its own policy. Missing translations do not bypass explicit read conditions.

Admin API also reads and accepts _translations. For example, PATCH an existing product with its shared fields while changing only the Russian translation:

{
  "id": 1,
  "price": 1490,
  "categoryId": 2,
  "_translations": {
    "ru": {
      "name": "Кружка с ручкой",
      "description": "Керамическая кружка, 300 мл."
    }
  }
}

This example assumes a model with the listed fields. Submit any other shared fields according to your own object contract. Missing languages and cells inside _translations are preserved; explicit null clears a translation when required-field rules allow it. Translation merging does not introduce arbitrary sparse PATCH updates of shared fields. External responses omit _translations. A translated-field uniqueness conflict within the same language returns HTTP 409; equal values in different languages do not conflict by themselves.

Related records

These suffixes extend the entity base address:

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.