Services API

A service is one runnable unit inside a project: a container in a docker-compose stack, or a sub-app in a monorepo. Both live in the same table (discriminated by kind), so this API covers listing and editing services, syncing them from a docker-compose file, starting/stopping/restarting their containers, resolving compose drift, and setting per-service environment variables. In the dashboard this is a project's Services tab; from the terminal it's openship service.

Endpoints

Add a service

POST /api/projects/:id/services

A service row is a union: kind: "compose" uses the container fields (image, build, ports…), while kind: "monorepo" uses the sub-app build fields (rootDirectory, framework…). Both field sets are accepted and optional; the kind decides which subset is the source of truth. Unknown keys are rejected.

Compose fields (used when kind is compose):

Monorepo sub-app fields (used when kind is monorepo):

curl -X POST https://your-host/api/projects/proj_123/services \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"db","kind":"compose","image":"postgres:16","ports":["5432:5432"]}'

# Same thing from the CLI:
openship service create -p my-stack db --image postgres:16 --port 5432:5432

Update a service

PATCH /api/projects/:id/services/:serviceId

Every field is optional — send only what changes. Accepts the same compose and monorepo fields as create, except kind: switching a row's kind is a destructive operation, so delete the service and re-create it under the new kind instead.

curl -X PATCH https://your-host/api/projects/proj_123/services/svc_456 \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"restart":"unless-stopped","enabled":true}'

Sync from docker-compose

Reads the project's docker-compose file and reconciles the service table to match it — adding, updating, and flagging services. Where your edits diverge from the compose file, the affected services are marked as drifted so you can resolve them explicitly (see below).

POST /api/projects/:id/services/sync

openship service sync -p my-stack docker-compose.yml

Resolve compose drift

When a service's stored config diverges from the upstream docker-compose file, it's flagged as drifted. Choose one resolution per service:

POST /api/projects/:id/services/:serviceId/drift/accept   # take upstream, discard your edits
POST /api/projects/:id/services/:serviceId/drift/keep     # keep your edits, stop flagging

openship service drift accept -p my-stack web
openship service drift keep   -p my-stack web

Container actions

Start, stop, or restart the running container for a single service. These act on the service's active-deployment container.

POST /api/projects/:id/services/:serviceId/start
POST /api/projects/:id/services/:serviceId/stop
POST /api/projects/:id/services/:serviceId/restart

openship service restart -p my-stack web

Use GET /api/projects/:id/services/containers (openship service containers -p my-stack) to list the running containers across the whole stack.

Environment variables

GET .../env lists a service's env vars (secret values masked). PUT .../env replaces the full set for one environment — send every var you want to keep.

GET /api/projects/:id/services/:serviceId/env
PUT /api/projects/:id/services/:serviceId/env

curl -X PUT https://your-host/api/projects/proj_123/services/svc_456/env \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment":"production","vars":[{"key":"DATABASE_URL","value":"postgres://…","isSecret":true}]}'

# Same thing from the CLI:
openship service env set -p my-stack web DATABASE_URL=postgres://… --env production

Errors you might see