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.
Catalog comes from Openship Cloud
The module is available on every deploy mode (self-hosted, cloud, and desktop), but the catalog itself is
served by Openship Cloud. On a SaaS instance it uses the master catalog; on a self-hosted instance
with a cloud account linked it uses your org's cloud token. On a self-hosted instance with no cloud
link, the endpoint returns an empty list with cloudConnected: false rather than an error — 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 "$OPENSHIP_URL/api/images" \
-H "Authorization: Bearer $OPENSHIP_TOKEN"
# With filters:
curl "$OPENSHIP_URL/api/images?search=postgres&category=database" \
-H "Authorization: Bearer $OPENSHIP_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 }. Link a cloud account to populate the catalog,
or 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
openship 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 |