Une API de flux exécute un flux réutilisable pour quiconque l’appelle. L’appelant envoie les entrées et les paramètres que le flux demande, et reçoit ses résultats sous forme de fichiers.
Une exécution peut prendre du temps; l’API répond donc tout de suite avec une exécution à suivre.
En créer une
Dans API Builder, commencez une nouvelle API et choisissez « API de flux ». Choisissez un flux réutilisable, puis « Créer l’API ».
La page montre ce que l’appelant envoie et ce qu’il reçoit. Les deux proviennent du flux lui-même; il n’y a donc rien à associer à la main.
Une API de flux compte pour une API dans votre forfait. C’est un brouillon tant que vous ne la publiez pas.
L’essayer
Sous Essayer, choisissez une couche pour chaque entrée, réglez les paramètres, choisissez le format de chaque résultat, puis sélectionnez Exécuter. Le flux s’exécute maintenant, en votre nom, sur les données de cet espace de travail. Chaque résultat revient sous forme de fichier à télécharger. C’est la même requête et les mêmes vérifications qu’un appel publié. Cela compte pour une exécution de flux, et rien n’est publié.
La publier
Choisissez « Publier sur Server ». La version publiée conserve exactement la version du flux que vous avez publiée. Enregistrer plus tard une version plus récente du flux ne change rien sur Server tant que vous n’avez pas choisi la nouvelle version sur la page de l’API et publié de nouveau.
Dans la console Server, créez une clé pour l’appelant et donnez-lui accès à l’API.
Lancer une exécution
Envoyez un POST à l’adresse /runs de l’API, avec la clé dans un en-tête.
curl -X POST "https://<your-server>/public/api/<organization>/<environment>/<api>/runs" \
-H "X-Api-Key: $TAMAAT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-42" \
-d '{
"inputs": {
"buildings": { "layer_id": "5da52cb6-3b4f-4db7-a12c-1a9047ddf735" },
"area": { "area": { "type": "Polygon", "coordinates": [[[-114.3, 50.9], [-113.8, 50.9], [-113.8, 51.2], [-114.3, 50.9]]] } }
},
"parameters": { "distance": 250 },
"wait_seconds": 20
}'
Chaque entrée prend l’une de ces formes :
| Envoyer | Pour |
|---|---|
{"layer_id": "…"} | Une couche que l’environnement est autorisé à lire |
{"geojson": …} | Vos propres entités, en FeatureCollection GeoJSON |
{"rows": […]} | Vos propres lignes de table |
{"area": …} | Un polygone, pour une entrée de type zone |
null | Une entrée facultative que vous omettez |
Les données envoyées avec une requête servent à cette exécution seulement. Elles ne deviennent jamais une couche de l’espace de travail. Une requête peut contenir jusqu’à 5 000 lignes pour une entrée.
La réponse est 202, avec l’exécution :
{
"run_id": "0c0f3f3e-7f5e-4a55-9c55-3f6b3c0e8f11",
"state": "queued",
"links": { "self": "/public/api/…/runs/0c0f3f3e-…", "cancel": "/public/api/…/runs/0c0f3f3e-…/cancel" }
}
Si quelque chose est incorrect dans la requête, la réponse est 422 et nomme chaque champ. Aucune exécution n’est lancée et rien n’est compté.
Attendre une exécution courte
Ajoutez wait_seconds, jusqu’à 60. Si l’exécution se termine dans ce délai, la réponse est 200, avec l’exécution terminée et ses résultats. Sinon, c’est 202 comme auparavant.
Réessayer sans risque
Envoyez un en-tête Idempotency-Key. Renvoyer la même requête avec la même clé renvoie la même exécution et n’en lance pas une seconde. Utiliser la clé avec une requête différente est refusé.
Suivre une exécution et récupérer les résultats
| Appel | Effet |
|---|---|
GET /runs/{run_id} | Renvoie l’exécution et son état |
POST /runs/{run_id}/cancel | Annule une exécution qui n’est pas terminée |
GET /runs/{run_id}/results/{key} | Renvoie un résultat sous forme de fichier |
Une exécution est queued, running, completed, failed ou cancelled. Les résultats ne sont présentés qu’une fois l’exécution terminée avec succès.
Un résultat de type couche revient en GeoJSON, ou en GeoParquet sur demande. Une table revient en CSV, ou en Parquet sur demande :
{ "formats": { "nearby": "geoparquet" } }
Une exécution ne répond qu’au consommateur de la clé qui l’a lancée. Toute autre personne se fait répondre qu’elle n’existe pas.
L’utiliser à partir d’un client IA
Avec les forfaits Delivery et Enterprise, une API de flux peut être offerte aux clients IA comme outil, au moyen du Model Context Protocol (MCP).
Dans la console Server, ouvrez l’API, allez dans Paramètres et activez « Offert aux assistants IA ». « Connecter un client IA » présente alors l’adresse et la configuration à coller dans le client.
Le client voit un outil par API de flux, avec les entrées et les paramètres du flux comme arguments. Un appel qui se termine rapidement reçoit ses résultats. Un appel plus long reçoit un identifiant d’exécution, que le client termine avec les outils run_status, run_result et run_cancel.
Ce que compte une exécution
Chaque exécution acceptée est une exécution ETL de l’espace de travail propriétaire de l’API, et sa durée compte comme temps de traitement. Chaque appel compte comme une requête d’API. Un appel refusé ne compte ni comme l’une ni comme l’autre.
Quand le flux est supprimé
Si le flux derrière une API de flux est placé dans la corbeille, la page de l’API affiche « Source dans la corbeille » et l’API ne peut pas être publiée de nouveau tant que le flux n’est pas restauré. Après une suppression définitive, elle affiche « Source requise ». Ce qui est déjà sur Server reste en ligne dans les deux cas.