API publique
Une petite API HTTP en lecture seule sur les projets, applications et déploiements de votre organisation. C'est la même surface que votre assistant IA voit à travers MCP : même jeton, mêmes données, mêmes limites — pour les fois où vous préférez un script, une tâche d'intégration continue ou un tableau de bord à un client de discussion.
Trois points d'accès pour l'instant. Ils sont en lecture seule : rien ici ne déploie, ne modifie ni ne supprime quoi que ce soit.
| Point d'accès | Ce qu'il renvoie |
|---|---|
GET /api/agent/projects | Tous les projets que vous pouvez voir, avec leurs environnements et leurs applications |
GET /api/agent/application | L'état, les réglages de build et les domaines d'une application |
GET /api/agent/deployments | Les déploiements récents d'une application, du plus récent au plus ancien |
Authentification
Utilisez le jeton d'assistant IA, et non une clé d'API de compte :
- Ouvrez Settings → AI.
- Sous Connect your AI assistant, cliquez sur Create token. Il n'est affiché qu'une fois : copiez-le.
Ce jeton est en lecture seule, personnel, et unique par personne et par organisation ; en créer un nouveau remplace le précédent, et Revoke le supprime immédiatement. Sa création exige la fonctionnalité d'assistant IA dans votre offre.
Transmettez-le dans l'un ou l'autre en-tête, ils sont équivalents :
export KUPLOY_URL="https://votre-instance-kuploy.com"
export KUPLOY_TOKEN="votre-jeton-assistant-ia"
curl -H "x-api-key: $KUPLOY_TOKEN" "$KUPLOY_URL/api/agent/projects"
curl -H "Authorization: Bearer $KUPLOY_TOKEN" "$KUPLOY_URL/api/agent/projects"
Les clés créées dans Account → API Keys authentifient le reste de l'API Kuploy — l'API d'import de site, par exemple — mais sont rejetées par ces points d'accès ; et le jeton d'assistant IA est rejeté partout ailleurs. La séparation est volontaire : un jeton que vous collez dans un client d'IA tiers ne doit jamais pouvoir modifier votre infrastructure.
Ce que vous pouvez voir
L'organisation est déduite du jeton : il n'y a aucun paramètre d'organisation, et un jeton ne peut pas atteindre les données d'une autre.
Au sein de votre organisation, l'API montre exactement ce que vous montre le tableau de bord :
- les propriétaires et administrateurs voient tous les projets ;
- un membre ne voit que les projets et services qui lui ont été accordés (Settings → Users → Add Permissions).
Ce qui ne vous a pas été accordé est signalé comme introuvable plutôt qu'interdit : l'API ne confirmera pas l'existence d'une application que vous n'avez pas le droit de voir. Un 404 signifie donc « aucune application de ce nom pour vous ».
Les points d'accès
Les tableaux ci-dessous sont générés à partir du document OpenAPI : ils ne peuvent donc pas diverger de ce que l'API renvoie — une évolution du schéma qui n'y serait pas répercutée fait échouer le build de la documentation.
Le corps de chaque réponse est la donnée elle-même : il n'y a pas d'objet enveloppe. Un champ marqué comme pouvant être nul peut revenir à null, et des champs non listés peuvent apparaître avec le temps : analysez les réponses avec souplesse et ignorez ce que vous ne connaissez pas.
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 |
Les erreurs
En cas de succès, c'est la donnée elle-même qui est renvoyée, sans objet enveloppe. Les erreurs renvoient { "message": …, "code": … } :
| Statut | code | Signification |
|---|---|---|
400 | BAD_REQUEST | Un paramètre manque ou sort des bornes. Le corps contient un tableau issues nommant le champ fautif. |
401 | UNAUTHORIZED | Jeton absent, révoqué, expiré ou d'un mauvais type — ou votre appartenance à l'organisation a été retirée. C'est aussi ce que vous obtenez en dépassant la limite de débit. |
404 | NOT_FOUND | Aucune application de ce nom, ou une application à laquelle vous n'avez pas accès. |
Limite de débit
120 requêtes par minute et par jeton. La limite porte sur le jeton lui-même : tout ce qui s'en sert puise dans la même enveloppe — votre client MCP et vos scripts se partagent les mêmes 120.
Un dépassement renvoie 401, exactement comme un jeton invalide, et sans en-tête Retry-After. Si des appels qui fonctionnaient il y a un instant reviennent soudain non autorisés alors que le jeton est toujours valide dans Settings → AI, c'est que vous êtes bridé : patientez une minute et ralentissez. Mettez en cache la liste des projets plutôt que de l'interroger en boucle.
Exemple : faire échouer une tâche CI si le dernier déploiement a échoué
#!/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
Exemple : lister toutes les applications et leur état
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)"'
Versionnement
L'API est décrite par un document OpenAPI (openapi.json, dans le dépôt Kuploy), à partir duquel vous pouvez générer un client.
The document is currently at version 2.1.0.
- Un nouveau point d'accès ou un champ de réponse supplémentaire relèvent d'une version mineure : vos appels existants continuent de fonctionner.
- La suppression d'un point d'accès, le renommage d'un champ ou la restriction d'une réponse relèvent d'une version majeure.
- Aucun point d'accès publié n'est retiré sans qu'une période de dépréciation ait d'abord été annoncée ici.
Les points d'accès qui ne figurent pas sur cette page ne font pas partie de l'API, même si vous parvenez à les atteindre. Ils peuvent changer ou disparaître sans changement de version.
Kuploy auto-hébergé
Les instances auto-hébergées servent ces mêmes points d'accès. Pour des raisons historiques, elles exposent aussi le reste de la surface tRPC interne sous /api/… ; les exploitants peuvent la restreindre aux seuls points d'accès publiés en définissant KUPLOY_PUBLIC_API_ONLY=true, après quoi tout le reste répond 404. Écrivez vos intégrations contre les points d'accès de cette page et ce réglage ne vous concernera pas.
Ces points d'accès ont brièvement répondu à /api/agentTools.listProjects, /api/agentTools.getApplication et /api/agentTools.listDeployments. La version 2.0.0 les déplace vers les chemins /api/agent/… ci-dessus — les anciennes adresses ont disparu, elles ne sont pas dépréciées. Elles n'ont existé que quelques jours, avant même cette page ; si l'un de vos scripts en utilise une, changez simplement l'URL. Rien d'autre n'a changé, ni dans les requêtes ni dans les réponses.