Projects API

A project is the unit Openship builds and runs: a source (a git repo, a local path, or an uploaded folder), its build configuration, environment variables, resource limits, domains, and deployment history. In the dashboard this is everything under a project's pages; from the terminal it's the openship projects command.

Endpoints

Create a project

POST /api/projects

Create a project from a git repo or a local path, baking the build config into the project row. For an uploaded folder, use the folder-upload flow instead. Only name is required — everything else is auto-detected or defaulted.

curl -X POST https://your-host/api/projects \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"marketing-site","gitOwner":"acme","gitRepo":"site","gitBranch":"main","framework":"nextjs"}'

# Same thing from the CLI:
openship projects create

Update a project

PATCH /api/projects/:id

The update body is a partial of the create body — send only the fields you want to change. Every field above is accepted and optional here.

curl -X PATCH https://your-host/api/projects/proj_123 \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildCommand":"pnpm build","gitBranch":"release"}'

openship projects update proj_123 --build-command "pnpm build"

Link a git repo

POST /api/projects/:id/git/link

Attach (or re-point) a GitHub repository to an existing project. When branch is omitted, the repo's default branch is used.

curl -X POST https://your-host/api/projects/proj_123/git/link \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"acme","repo":"site","branch":"main"}'

Related git routes: POST /api/projects/:id/branch (change the deploy branch), POST /api/projects/:id/auto-deploy (toggle deploy-on-push), GET /api/projects/:id/branches, and GET /api/projects/:id/commit-status (is the deployed commit behind remote HEAD?). See the GitHub API for connecting the GitHub App itself.

Connect a custom domain

POST /api/projects/:id/connect

A shortcut that adds a domain to the project and marks it primary in one call. For the full domain lifecycle (DNS preview, verification, SSL), use the Domains API.

curl -X POST https://your-host/api/projects/proj_123/connect \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.example.com"}'

Environment variables

GET   /api/projects/:id/env
PATCH /api/projects/:id/env

GET lists variables for the project with secret values masked. Writes go through a merge: only the keys you name are touched — upserts are inserted/updated, deletes are removed, and every other variable (including untouched masked secrets) is left intact.

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

openship env set DATABASE_URL="postgres://…" --project proj_123 --secret

Resources

GET   /api/projects/:id/resources
PATCH /api/projects/:id/resources
POST  /api/projects/:id/resources

Read or update the CPU/RAM/disk allotment (separately for production and build), sleep behavior, and listen port. POST is an alias of PATCH. All fields are optional; send only what you want to change.

curl -X PATCH https://your-host/api/projects/proj_123/resources \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"production":{"cpuCores":1,"memoryMb":1024},"sleepMode":"always_on"}'

Sleep mode also has its own shortcut route: POST /api/projects/:id/sleep-mode.

Create an environment

POST /api/projects/:id/environments

Folder-upload deploy

Deploy a local folder from a browser or client that shares no filesystem with the API. The flow is four steps; the binary tarball upload happens out-of-band (raw bytes, not JSON).

The upload target is deliberately opaque — it points at this API's relay on a self-hosted instance and straight at a build workspace on Openship Cloud. Use absoluteUrl as-is, or resolve the API-relative url against your own API base. When requiresAuth is true (the self-hosted relay), send the same Authorization: Bearer <token> you used to open the session in addition to upload.headers — the relay is permission-checked like every other route. When it's false, the target is external and carries its own credential in headers; never add your Openship token to it.

The session body (POST /api/projects/folder/session) is a lightweight hint — all fields optional:

POST /api/projects/ensure takes the full create body plus an optional projectId to update an existing project in place instead of creating a new one. Set gitProvider: "upload" for a folder-upload project.

Multi-service folders

When the uploaded folder has a docker-compose.yml, the scan returns a services array. Pass it through to POST /api/projects/ensure verbatim and it becomes the project's service set — ensure owns those rows, so send the whole set (services you leave out are removed, same as POST /api/projects/:id/services/sync). If you skip it, the deploy step falls back to the services the scan parsed for that upload session, so the four-step flow works either way; passing them explicitly is what lets you review or edit the set before deploying.

Transfer to / from cloud

POST /api/projects/:id/transfer/to-cloud         † self-hosted only
POST /api/projects/:id/transfer/to-self-hosted   † self-hosted only

Promote a local project to Openship Cloud, or pull a cloud project back to this instance. These are meaningless on the SaaS (it is the cloud) and return 404 there. Both require project:admin.

curl -X POST https://your-host/api/projects/proj_123/transfer/to-cloud \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Errors you might see