Vue d'ensemble

L'API Ephemeral est une API JSON sur HTTPS. Les exécutions, les workflows, les fichiers, les connexions et les modèles sont servis par le moteur. Sur le service hébergé, les organisations, les membres, les clés et la facturation sont servis par une API d'organisation distincte.

URL de base

Les exemples de ces pages utilisent $EPHEMERAL_URL pour la base du moteur, sans le /v1.

Authentification

Envoyez une clé API d'organisation comme jeton bearer à chaque requête vers le moteur.

curl $EPHEMERAL_URL/v1/me \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

Les clés hébergées commencent par eak_ ; les clés auto-hébergées commencent par eph_. Une clé appartient à une seule organisation : vous ne transmettez donc jamais d'ID d'organisation au moteur. La possibilité pour une clé d'appeler un endpoint dépend de son rôle ; voir rôles et clés. L'API d'organisation refuse les clés API pour les actions de gestion et exige à la place un propriétaire ou un administrateur connecté ; voir organisations.

Les applications qui agissent pour une personne, comme les clients MCP, peuvent se connecter avec OAuth 2.1 à la place (service hébergé uniquement) : flux de code d’autorisation avec PKCE, enregistrement dynamique des clients et les portées member et admin. Le jeton d’accès (eoa_…, valable une heure) va dans le même en-tête Authorization: Bearer et agit dans l’organisation choisie par la personne. Découverte : métadonnées du serveur d’autorisation et métadonnées de ressource protégée. Voir MCP.

{
  "organization_id": "org_5e2b8c91d4a7f03e6b1c9d2a8f4e7b10",
  "role": "member",
  "mode": "hosted",
  "compute_micros_per_second": 200,
  "default_max_cost_micros": 500000
}

Requêtes

• Envoyez du JSON avec Content-Type: application/json. Les imports de fichiers font exception et utilisent des données de formulaire multipart.
• Les champs inconnus sont rejetés avec 400 : un champ mal orthographié renvoie donc une erreur.
• Les horodatages sont des chaînes RFC 3339 en UTC.
• Les champs monétaires se terminant par _micros sont des millionièmes entiers de dollar américain. Ceux qui se terminent par _cents sont des cents entiers.

Erreurs

Les erreurs renvoient un statut HTTP et un corps JSON avec un message lisible dans error.

{ "error": "timeout_seconds must be between 1 and 3600", "code": "invalid_request" }

Limites de débit

Les requêtes vers le moteur sont limitées par minute. Une requête avec un jeton porteur est comptée pour cet identifiant, à raison de 600 requêtes par minute. Une requête sans jeton, comme GET /v1/models, est comptée pour l'adresse du client, à raison de 120 requêtes par minute. La fenêtre dure une minute et repart au début de chaque minute.

Chaque réponse du moteur, erreurs comprises, indique où vous en êtes. RateLimit-Policy et RateLimit suivent le brouillon de l'IETF sur les en-têtes RateLimit (q est le quota, w la fenêtre en secondes, r les requêtes restantes et t les secondes avant la réinitialisation). X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset donnent les mêmes valeurs sous les noms que de nombreux clients lisent déjà.

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=41
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 41

Au-delà de la limite, le moteur répond 429 avec l'erreur JSON habituelle, le code rate_limited et un en-tête Retry-After indiquant les secondes à attendre. Patientez ce délai au lieu de réessayer aussitôt. Suivre une exécution avec GET /v1/runs/{id}/events compte une fois par connexion, et non par événement.

Création d'exécution idempotente

Une panne réseau peut vous laisser dans l'incertitude : l'exécution a-t-elle été créée ? Envoyez un en-tête Idempotency-Key, de 200 caractères au maximum, avec POST /v1/runs. Si une exécution portant cette clé existe déjà dans votre organisation, Ephemeral la renvoie avec le statut 200 au lieu d'en créer une autre. Une nouvelle exécution renvoie 202.

Pagination

GET /v1/runs pagine lorsque vous passez limit (de 1 à 100) ou cursor. La réponse est {"items": [...], "next_cursor": "..."}. Renvoyez next_cursor dans cursor pour obtenir la page suivante ; un next_cursor vide signifie que vous avez atteint la dernière. Les curseurs sont opaques et ne sont valides qu'avec le même filtre status. Sans limit ni cursor, la réponse est un simple tableau des 100 exécutions les plus récentes.

Versions et dépréciation

L'API est versionnée dans son chemin : tous les endpoints ici sont sous /v1. Au sein d'une version, les changements ne font qu'ajouter : nouveaux endpoints, nouveaux champs de requête facultatifs, nouveaux champs de réponse et nouveaux types d'événements. Les champs existants gardent leur nom et leur sens ; les clients doivent ignorer les champs qu'ils ne connaissent pas.

Un changement qui casserait les clients existants est publié comme une nouvelle version sous un nouveau chemin. La version précédente continue de fonctionner au moins six mois après la publication de la nouvelle. Pendant sa dépréciation, ses réponses portent un en-tête Deprecation et un en-tête Sunset indiquant la date d'arrêt, et les propriétaires d'organisation sont prévenus par e-mail.

Référence

L'API du moteur est aussi publiée sous la forme d'une description OpenAPI 3.1 (https://app.ephemer.al/openapi.json), avec le rôle de clé que chaque opération exige. Les rôles de clé, member et admin, sont listés dans scopes_supported, lisible par une machine, dans les métadonnées de la ressource protégée.