REST API

The API is HTTP over JSON. Everything lives under /api on the same host as the dashboard.

https://clikdeploy.com/api

If you run your own instance, use your own host instead. The paths are the same.

A successful response is a JSON object with success: true and the result under data.

{
  "success": true,
  "data": {
    "id": "cmd8x1a2b0000abcd",
    "appId": "cmd7w0z1y0000wxyz",
    "status": "RUNNING",
    "createdAt": "2026-07-28T09:12:44.001Z"
  }
}

List endpoints add a pagination object next to data, and accept ?page= and ?pageSize= query parameters.

{
  "success": true,
  "data": [ /* apps */ ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 7,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Every response carries an x-request-id header. Quote it if you ever need to report a problem — it is the id the platform logs the request under.

Every request is authenticated with a bearer credential in the Authorization header. There are two kinds.

An API key — for your own account

An API key acts as you. Use it for scripts, CI jobs and anything that only touches your own resources.

Create one in the dashboard: open Settings from the account menu, go to the Developer tab, and generate a key. From a terminal, the CLI does the same thing.

clikdeploy user api-keys create "ci-pipeline"

A key looks like cd_live_ followed by 64 hex characters. Send it as a bearer token.

curl https://clikdeploy.com/api/apps \
  -H "Authorization: Bearer cd_live_YOUR_KEY"

An OAuth access token — for someone else's account

If you are building an app that acts on behalf of other ClikDeploy users, you do not ask them for an API key. You send them through ClikOAuth, they approve a set of scopes, and your app receives an access token. That token goes in the same header, and works against the same endpoints — narrowed to the scopes the user approved.

The full authorization flow is on the ClikOAuth page.

A scope is a permission string that says which slice of the platform a credential can touch. It has two parts: an area, and either read or write.

apps:read      list and inspect apps
apps:write     also create, change and deploy them

Write includes read. Granting deploy:write also grants deploy:read, so you never need to ask for both.

There are 50 scopes in total. Twelve of them are admin scopes (admin- prefix) for platform operators; they are never granted to an app that registered itself, and they are necessary but not sufficient — the account still has to hold the admin role. Four are the OpenID Connect identity scopes: openid, profile, email and offline_access.

Here are ten of the ones you are most likely to want.

The complete list is published in the discovery document, under scopes_supported, so you never have to keep a copy in sync.

curl https://clikdeploy.com/.well-known/oauth-authorization-server

Which scope an endpoint needs

The scope is derived from the path and the method: GET needs the read scope of whichever area owns the path, anything else needs the write scope. The area is the first part of the path, not the last — so a deploy triggered at POST /api/apps/{id}/deploy is an apps:write operation, while GET /api/deployments/{id} is deploy:read.

A path that has no scope mapping is refused for an OAuth token rather than allowed by default. If you get a 403 on a path you expected to reach, that is why.

Nothing changes for you. An API key with no scope list attached is a full-access key, and every key issued before scopes existed is one. Scope checks are skipped entirely for those keys, so existing scripts, CI jobs and CLI installs keep working exactly as they did.

Keys you create today are full-access too. Scopes are how you hand out narrower access to other people's tools, through ClikOAuth — not something you have to configure to keep your own key working.

A browser session in the dashboard is also always full access.

Errors are JSON, and the HTTP status is the thing to branch on. Most come back as application/problem+json (RFC 7807).

{
  "type": "https://errors.clikdeploy.com/AUTH_REQUIRED",
  "title": "Invalid API key",
  "status": 401,
  "code": "AUTH_REQUIRED",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

A few endpoints answer with { "success": false, "error": "..." } instead, usually for a bad request body. Read the status code first and treat the body as detail.

A 403 tells you which scope was missing

When the 403 is a scope problem, the response carries a WWW-Authenticate header naming the scope to ask for. That is what lets an OAuth client send the user back to re-authorize instead of just failing.

WWW-Authenticate: Bearer error="insufficient_scope",
  error_description="This request requires additional scope", scope="apps:write"

{
  "type": "https://errors.clikdeploy.com/FORBIDDEN",
  "title": "Insufficient scope. This request requires: apps:write",
  "status": 403,
  "code": "FORBIDDEN",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

Limits are per user and are applied per route family, not to the API as a whole. These are the ones you are likely to meet.

Rate-limited responses include the current state of your bucket, on both successful and refused requests.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1785318000

When you go over, you get a 429 with a Retry-After header in seconds. The body repeats it.

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 34,
  "reset": 1785318000
}

Wait for Retry-After and retry. Other route families have their own limits; read the headers rather than assuming a number.

This is the whole flow — find an app, redeploy it, watch it finish, read its logs. Export your key once and every command below works as written.

export CLIK_KEY=cd_live_YOUR_KEY
export CLIK_API=https://clikdeploy.com

1. List your apps

curl -s "$CLIK_API/api/apps" \
  -H "Authorization: Bearer $CLIK_KEY"

This doubles as a credential check: a 200 means the key is good. Each item in data is an app. The fields you need next are id, name, status and domain.

{
  "success": true,
  "data": [
    {
      "id": "cmd7w0z1y0000wxyz",
      "name": "storefront",
      "status": "RUNNING",
      "domain": "storefront.example.com",
      "port": 3000,
      "serverId": "cmd6v9y0x0000stuv"
    }
  ],
  "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1,
                  "hasNextPage": false, "hasPreviousPage": false }
}

status is one of RUNNING, STOPPED, DEPLOYING, RESTARTING, RECOVERING, ERROR or NOT_FOUND.

2. Trigger a deploy

Post to the app's deploy endpoint. An empty body redeploys the app as it is configured today, which is what you usually want.

curl -s -X POST "$CLIK_API/api/apps/cmd7w0z1y0000wxyz/deploy" \
  -H "Authorization: Bearer $CLIK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The response is the new deployment row. Keep its id — that is what you poll.

{
  "success": true,
  "data": {
    "id": "cmd8x1a2b0000abcd",
    "appId": "cmd7w0z1y0000wxyz",
    "status": "QUEUED",
    "gitBranch": "main",
    "createdAt": "2026-07-28T09:12:44.001Z"
  },
  "message": "Deployment started"
}

Optional fields you can send in the body:

• gitCommit — deploy a specific commit rather than the branch head.
• envVars — an object of string values, merged for this deploy.
• dockerImage — deploy a specific image instead of building from source.
• port — the port your app listens on, if it changed.
• pullImage — true to force a fresh pull of the image.

3. Poll until it finishes

curl -s "$CLIK_API/api/deployments/cmd8x1a2b0000abcd" \
  -H "Authorization: Bearer $CLIK_KEY"

data.status moves from QUEUED to RUNNING and then settles on SUCCESS, FAILED, CANCELLED or ROLLED_BACK. On a failure, data.error holds the reason and data.errorCode a stable code.

while true; do
  STATUS=$(curl -s "$CLIK_API/api/deployments/cmd8x1a2b0000abcd" \
    -H "Authorization: Bearer $CLIK_KEY" | jq -r .data.status)
  echo "$STATUS"
  case "$STATUS" in SUCCESS|FAILED|CANCELLED|ROLLED_BACK) break ;; esac
  sleep 5
done

Build output for the same deployment is at GET /api/deployments/{id}/logs.

4. Read the running app's logs

Once the deployment succeeds, this returns the container's output as a single string. limit is the number of lines, default 2000, capped at 10000.

curl -s "$CLIK_API/api/apps/cmd7w0z1y0000wxyz/logs?limit=200" \
  -H "Authorization: Bearer $CLIK_KEY"

{
  "success": true,
  "data": "2026-07-28T09:13:02Z listening on :3000\n..."
}

If the container cannot be reached, the response carries "fallback": true and data is the stored deployment log replayed instead of live output. Check that flag before concluding the app is healthy.

• Acting on behalf of other users: ClikOAuth.
• The same operations as tools for an AI agent: Agents & MCP.
• Being told when a deploy finishes instead of polling for it: Events & webhooks.
• The same operations from a terminal: CLI.