API guide

Everything in i3deploy — deploys, projects, services, and releases — is available over a plain REST API at https://backend.i3deploy.com. This page covers auth and the key endpoints; for the full interactive reference, see:

Swagger UI — browse every endpoint, try requests from the browser.
Redoc — the same schema as a static, readable reference doc.

Auth

Every request needs an API key, sent as a bearer token:

curl https://backend.i3deploy.com/v1/deploys \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY"

Create a key from the API Keys page in the app (app.i3deploy.com → your org → API Keys). The key is shown once at creation time — copy it somewhere safe.

Keys are org-scoped, not user-scoped: whichever organization the key belongs to is the only one it can read or write. There's no separate "project" or "service" scope — one key covers every project and service in the org, so one key per CI system or integration is usually enough.

Key endpoints

`POST /v1/deploys` — start a deploy

curl -X POST https://backend.i3deploy.com/v1/deploys \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"web","env":"production","version":"1.4.2","commit_sha":"abc123"}'

See the Quickstart for the full start/finish flow and the vendored i3deploy.sh script.

`GET /v1/projects` — list projects, `POST` to create one

curl -X POST https://backend.i3deploy.com/v1/projects \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"marketing-site","title":"Marketing site"}'

`GET /v1/services` — list services, `POST` to create one

curl -X POST https://backend.i3deploy.com/v1/services \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"web","project":"marketing-site","display_name":"Web"}'

`POST /v1/service-releases` — record a service's changelog

curl -X POST https://backend.i3deploy.com/v1/service-releases \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"web","version":"1.4.2","commit_sha":"abc123","changelog_markdown":"- Fixed the checkout redirect loop"}'

`POST /v1/project-releases` — bundle service releases into a project release

curl -X POST https://backend.i3deploy.com/v1/project-releases \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"marketing-site","title":"2.4","version_numeric":"2.4.0","markdown_users":"Fixed checkout","service_releases":[{"service":"web","version":"1.4.2"}]}'

See Cutting releases for the full ServiceRelease/ProjectRelease model and field shapes.

`GET /v1/api-keys` — list your org's keys, `POST` to mint one

Key management is one level up from everything else: it's only available to a logged-in user account (never another API key — a limited key can't mint itself a broader one), and it takes an organization query param to pick which org's keys you're managing:

curl -X POST "https://backend.i3deploy.com/v1/api-keys?organization=acme-inc" \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-pipeline"}'

In practice you'll do this from the API Keys page in the app rather than curl. The response includes the raw secret — that's the only time it's ever returned. Store it now; every later GET on this endpoint omits it.

`GET /v1/organizations` — the orgs your key (or account) can see

curl https://backend.i3deploy.com/v1/organizations \
  -H "Authorization: Bearer $I3DEPLOY_API_KEY"

POST to this endpoint creates a new organization, but only for a logged-in user account, not an API key — it's tied to per-user ownership limits, so create new orgs from the app UI instead of CI.

Everything else

The list above covers what most integrations need. For the full set of endpoints, request/response shapes, and fields, use the Swagger UI or Redoc — both are generated straight from the live schema, so they never drift from what the server actually accepts.