Référence API

🌐 Base URL

Toutes les requêtes sont relatives à la racine /api de votre instance :

http://localhost:3000/api

La spécification OpenAPI est disponible publiquement (aucune authentification requise) :

• JSON : GET /api/openapi.json
• Swagger UI : GET /api/docs

🔐 Authentification

L'API supporte deux méthodes d'authentification.

Cookie session

Utilisée par le frontend. L'authentification repose sur Better Auth avec email/mot de passe et login social optionnel (Google, GitHub). Le cookie de session est envoyé automatiquement par le navigateur.

Pour les routes scopées à une organisation, ajoutez le header X-Org-Id :

curl -b cookies.txt \
  -H "X-Org-Id: org_abc123" \
  http://localhost:3000/api/applications

Clé API

Pour les intégrations headless. Les clés API utilisent le préfixe ask_ et sont scopées à une application.

curl -H "Authorization: Bearer ask_votre_clé" \
     -H "X-App-Id: app_abc123" \
     http://localhost:3000/api/agents

Le header X-App-Id est requis pour les routes scopées à une application : agents, runs, schedules, webhooks, end-users, api-keys, packages, providers et connections.

SSE et clés API

Les endpoints SSE (Server-Sent Events) ne supportent pas les headers custom via EventSource. Passez la clé API en query param :

curl -N "http://localhost:3000/api/realtime/runs/run_abc?token=ask_votre_clé"

👤 Impersonation d'end-users

L'API permet d'exécuter des requêtes au nom d'un end-user via le header Appstrate-User :

curl -H "Authorization: Bearer ask_votre_clé" \
     -H "X-App-Id: app_abc123" \
     -H "Appstrate-User: eu_xyz789" \
     http://localhost:3000/api/runs

Contraintes :

• Clé API uniquement — retourne 400 si utilisée avec une session cookie
• L'end-user doit appartenir à l'application associée à la clé API
• Toutes les requêtes sont tracées dans le journal d'audit (requestId, apiKeyId, endUserId, applicationId, IP, userAgent)

🔢 Versioning de l'API

L'API utilise un versioning basé sur les dates, inspiré du modèle Stripe. Envoyez le header Appstrate-Version pour cibler une version spécifique :

Appstrate-Version: 2026-03-21

• Sans header : utilise la version épinglée de l'organisation, ou la version courante par défaut
• Épinglage : configurez la version par défaut dans les paramètres de votre organisation
• Deprecation : les versions obsolètes retournent un header Sunset avec la date de fin de support

⚠️ Format d'erreur

Toutes les erreurs suivent la spécification RFC 9457 (application/problem+json). Chaque réponse inclut un header Request-Id (préfixe req_) pour le suivi.

{
  "type": "https://appstrate.dev/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Le champ 'name' est requis et ne peut pas être vide.",
  "instance": "/api/agents"
}

Le Request-Id est présent sur toutes les réponses (succès et erreurs) :

Request-Id: req_a1b2c3d4e5f6

🚦 Rate limiting

Le rate limiting est backed par Redis via rate-limiter-flexible. Les clés sont construites à partir de la méthode, du path et de l'identifiant de l'appelant :

• Session cookie : method:path:userId
• Clé API : method:path:apikey:apiKeyId

Chaque réponse inclut les headers IETF standard :

RateLimit: limit=20, remaining=18, reset=45
RateLimit-Policy: 20;w=60

En cas de dépassement (429 Too Many Requests), un header Retry-After indique le délai en secondes.

Limites principales :

🔁 Idempotence

Les routes POST critiques (end-users, webhooks, lancement de run) supportent le header Idempotency-Key pour garantir l'idempotence :

curl -X POST \
     -H "Authorization: Bearer ask_votre_clé" \
     -H "X-App-Id: app_abc123" \
     -H "Idempotency-Key: my-unique-key-123" \
     -H "Content-Type: application/json" \
     -d '{"agentId": "agent_abc"}' \
     http://localhost:3000/api/runs

Comportement :

• Les clés sont stockées dans Redis avec un TTL de 24 heures
• Un hash SHA-256 du body est utilisé pour détecter les conflits
• 409 Conflict : requête concurrente avec la même clé (traitement en cours)
• 422 Unprocessable Entity : même clé mais body différent
• Les replays retournent le header Idempotent-Replayed: true

📄 Pagination

Les endpoints de liste utilisent une pagination offset-based :

curl -H "Authorization: Bearer ask_votre_clé" \
     -H "X-App-Id: app_abc123" \
     "http://localhost:3000/api/agents?page=2&pageSize=20"

Format de réponse :

{
  "data": [{ "id": "agent_abc", "name": "Mon agent" }],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "total": 47,
    "totalPages": 3
  }
}

📡 Streaming SSE (temps réel)

L'API expose des endpoints SSE pour suivre les runs en temps réel. Les événements incluent les changements de statut et les entrées de log.

Exemple de connexion avec clé API :

curl -N -H "Accept: text/event-stream" \
     "http://localhost:3000/api/realtime/runs/run_abc?token=ask_votre_clé"

Pour l'authentification par cookie, les headers standard (Cookie, X-Org-Id) sont utilisés normalement.