Public API
A small, read-only HTTP API over your organization's projects, applications and deployments. It's the same surface your AI assistant sees through MCP: the same token, the same data, the same limits, for when you want a script, a CI job or a status board instead of a chat client.
Three endpoints today. They are read-only: nothing here deploys, changes or deletes anything.
| Endpoint | Returns |
|---|---|
GET /api/agent/projects | Every project you can see, with its environments and applications |
GET /api/agent/application | One application's status, build settings and domains |
GET /api/agent/deployments | An application's recent deployments, newest first |
Authentication
Use the AI assistant token, not an Account API key:
- Open Settings → AI.
- Under Connect your AI assistant, click Create token. It is shown once — copy it.
The token is read-only, personal, and one per person per organization; creating a new one replaces the old one, and Revoke kills it immediately. Minting it requires the AI assistant on your plan.
Send it in either header — they are equivalent:
export KUPLOY_URL="https://your-kuploy-instance.com"
export KUPLOY_TOKEN="your-ai-assistant-token"
curl -H "x-api-key: $KUPLOY_TOKEN" "$KUPLOY_URL/api/agent/projects"
curl -H "Authorization: Bearer $KUPLOY_TOKEN" "$KUPLOY_URL/api/agent/projects"
The keys from Account → API Keys authenticate the rest of the Kuploy API (for example the Site Import API) but are rejected by these endpoints, and the AI assistant token is rejected everywhere else. The two are deliberately separate: a token you paste into a third-party AI client should never be able to change your infrastructure.
What you can see
The organization comes from the token — there is no organization parameter, and a token cannot reach another organization's data.
Within your organization, the API shows exactly what the dashboard shows you:
- Owners and admins see every project.
- A member sees only the projects and services they were granted (Settings → Users → Add Permissions).
Anything you weren't granted is reported as not found rather than forbidden — the API won't confirm that an application exists if you can't see it. So a 404 means "no such application for you".
Endpoints
The tables below are generated from the OpenAPI document, so they cannot drift from what the API returns — a spec change that isn't reflected here fails the docs build.
Every response body is the data itself: there is no wrapper object. A field marked nullable can come back null; fields not listed may appear over time, so parse leniently and ignore what you don't know.
GET /api/agent/application
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
applicationId | query | yes | string | min length 1 |
curl -H "x-api-key: $KUPLOY_TOKEN" \
"$KUPLOY_URL/api/agent/application?applicationId=<applicationId>"
Returns an object.
| Field | Type | Nullable |
|---|---|---|
applicationId | string | no |
name | string | no |
appName | string | no |
applicationStatus | string | yes |
buildType | string | yes |
sourceType | string | yes |
createdAt | string | no |
project | object | no |
project.projectId | string | no |
project.name | string | no |
environment | object | no |
environment.environmentId | string | no |
environment.name | string | no |
domains | array of object | no |
domains[].host | string | no |
domains[].port | number | yes |
domains[].https | boolean | yes |
GET /api/agent/deployments
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
applicationId | query | yes | string | min length 1 |
limit | query | no | integer | default 10, min 1, max 50 |
curl -H "x-api-key: $KUPLOY_TOKEN" \
"$KUPLOY_URL/api/agent/deployments?applicationId=<applicationId>"
Returns an array.
| Field | Type | Nullable |
|---|---|---|
[].deploymentId | string | no |
[].status | string | yes |
[].title | string | no |
[].description | string | yes |
[].createdAt | string | no |
[].startedAt | string | yes |
[].finishedAt | string | yes |
GET /api/agent/projects
No parameters.
curl -H "x-api-key: $KUPLOY_TOKEN" \
"$KUPLOY_URL/api/agent/projects"
Returns an array.
| Field | Type | Nullable |
|---|---|---|
[].projectId | string | no |
[].name | string | no |
[].description | string | yes |
[].createdAt | string | no |
[].environments | array of object | no |
[].environments[].environmentId | string | no |
[].environments[].name | string | no |
[].environments[].applications | array of object | no |
[].environments[].applications[].applicationId | string | no |
[].environments[].applications[].name | string | no |
[].environments[].applications[].appName | string | no |
[].environments[].applications[].applicationStatus | string | yes |
[].environments[].applications[].createdAt | string | no |
Errors
Success returns the data itself — there is no wrapper object. Errors return { "message": …, "code": … }:
| Status | code | Means |
|---|---|---|
400 | BAD_REQUEST | A parameter is missing or out of range. The body carries an issues array naming the field. |
401 | UNAUTHORIZED | Missing, revoked, expired or wrong kind of token — or your membership in the organization was removed. Also what you get when you exceed the rate limit. |
404 | NOT_FOUND | No such application, or one you weren't granted access to. |
Rate limit
120 requests per minute per token. The limit lives on the token itself, so everything using it draws from one budget — your MCP client and your scripts compete for the same 120.
Going over answers 401, the same as an invalid token, with no Retry-After. So if calls that worked a moment ago suddenly come back unauthorized while the token is still valid in Settings → AI, you're being throttled: back off for a minute and slow down. Cache the project listing rather than polling it.
Example: fail a CI job when the last deploy didn't succeed
#!/usr/bin/env bash
set -euo pipefail
APP_ID="app_71b…"
last=$(curl -fsS -H "x-api-key: $KUPLOY_TOKEN" \
"$KUPLOY_URL/api/agent/deployments?applicationId=$APP_ID&limit=1")
status=$(echo "$last" | jq -r '.[0].status')
echo "last deployment: $status"
[ "$status" = "done" ] || exit 1
Example: list every application and its status
curl -fsS -H "x-api-key: $KUPLOY_TOKEN" "$KUPLOY_URL/api/agent/projects" \
| jq -r '.[] | .name as $p
| .environments[] | .name as $e
| .applications[]
| "\($p)/\($e)/\(.name)\t\(.applicationStatus)"'
Versioning
The API is described by an OpenAPI document (openapi.json in the Kuploy repository), which you can generate a client from.
The document is currently at version 2.1.0.
- A new endpoint or an added response field is a minor bump — your existing calls keep working.
- A removed endpoint, a renamed field or a narrowed response is a major bump.
- No published endpoint is removed without a deprecation window announced here first.
Endpoints that are not listed on this page aren't part of the API, even if you can reach them. They can change or disappear without a version bump.
Self-hosted Kuploy
Self-hosted instances serve these same endpoints. They also expose the rest of the internal tRPC surface over /api/… for historical reasons; operators can restrict it to the published endpoints by setting KUPLOY_PUBLIC_API_ONLY=true, after which everything else answers 404. Write your integrations against the endpoints on this page and that switch won't affect you.
The endpoints briefly answered at /api/agentTools.listProjects, /api/agentTools.getApplication and /api/agentTools.listDeployments. Version 2.0.0 moves them to the /api/agent/… paths above — the old spellings are gone, not deprecated. They existed for a few days before this page did; if a script of yours uses one, update the URL. Nothing else about the requests or responses changed.