Quickstart

This guide gets you ready to use the Depfloy API. We'll cover the endpoint, required headers, how to authenticate, and how to make your first request.

AUTH Authorization: Bearer {API_KEY} Create a token →

Endpoint #

The Depfloy API is available at:

https://app.depfloy.com/api/v1

Headers #

The following headers are required on every request:

Authorization: Bearer {API_KEY}
Content-Type: application/json
Accept: application/json

One header is optional:

X-Organization: {ORGANIZATION_ID}

It picks which of your organizations the request runs in. Without it, the request uses whichever organization your account is currently in.

Authentication #

Depfloy uses Bearer Token authentication. Create a token under Configuration → API Tokens — the value is shown only once at creation, so copy it somewhere safe immediately.

curl https://app.depfloy.com/api/v1/projects \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Each token carries its own permission set. Grant only the permissions a specific integration needs — see API Tokens for the full create / revoke flow.

A token’s permissions narrow what it can do; they do not widen it. Your role on the organization still applies, and so does any restriction to specific servers or projects on your membership. A token issued with deployment:create cannot deploy a project your membership does not reach.

Which organization a request runs in #

The API answers within one organization at a time — the same boundary the Console shows you.

  • One organization on the account: nothing to think about. This section changes nothing for you.
  • Several organizations: a request without X-Organization runs in whichever one your account is currently in. Send the header to pick another for that request only — it does not move your Console, and two tools can work in different organizations at the same time.
  • You can only name an organization you belong to; anything else is answered 403.
  • Your role in that organization is what applies. Owner in one and Viewer in another means Viewer’s permissions when you name the second.
  • An id from another organization is not visible while acting in one, so a request cannot cross over by accident — it is answered 404.

GET /api/v1/me lists the organizations you belong to, with their ids.

This narrowed in 2026. Before it, a token reached everything on the account regardless of organization or of any per-server restriction on your membership — the Console applied both and the API did not. They match now. Accounts that never used organizations are unaffected.

Rate limits #

API requests are limited to 120 per minute. If you exceed the limit, requests are answered with 429 Too Many Requests. Back off and retry, or stagger your requests.

The count is per user, not per token. Two tokens belonging to the same person share one budget, so issuing a second token to work around a limit does not raise it. The MCP endpoint has its own separate allowance.

What’s next? #