Container images
Browse container images for project services.
The Images API returns the build-image catalog — the curated list of ready-made service images (PostgreSQL, Redis, and friends) you pick from when adding a service to a project. In the dashboard this is the image grid in the Add service modal; it's a read-only lookup, so there's nothing to create or edit.
The catalog comes from a hosted cloud
The module is available on every deploy mode (self-hosted, cloud, and desktop), but the catalog itself is
served by a hosted cloud, which is switched off in Synq. On a self-hosted instance with no cloud link
(every Synq install), the endpoint returns an empty list with cloudConnected: false rather than an
error, and the dashboard falls back to the "Custom image" tile. Results are cached in memory for a few minutes.
List images
Returns the catalog for your organization. Both filters are optional and applied by the upstream catalog; omit them to get everything.
GET /api/imagesProp
Type
curl "$SYNQ_URL/api/images" \
-H "Authorization: Bearer $SYNQ_TOKEN"
# With filters:
curl "$SYNQ_URL/api/images?search=postgres&category=database" \
-H "Authorization: Bearer $SYNQ_TOKEN"The response is { "success": true, "images": [ … ] }. Each entry describes one catalog image; common fields
are id (slug you pick), name (display name), image (the Docker image string), description,
category, logo, tags, ports, and defaultEnv (suggested env keys). Additional fields returned by the
upstream catalog are passed through unchanged for forward compatibility.
Errors
Empty catalog with cloudConnected: false
Not an error. On a self-hosted instance with no cloud account linked, the response is
{ "success": true, "images": [], "cloudConnected": false }. On Synq that's the normal response: supply a
custom image directly on the service.
500 — failed to list images
The upstream catalog call failed. The response is { "success": false, "error": "…" }. Retry after a
moment; the result is cached once fetched.
401 — unauthorized
No valid session cookie or bearer token was supplied. Create a token with
synq token create and send it as Authorization: Bearer <token>.
Operations
| Operation | REST API |
|---|---|
List available build/service images, optionally filtered by ?search= and ?category=. | GET /api/imagesAuthenticated |