Una API de flujo ejecuta un flujo reutilizable para quien la llame. Quien llama envía las entradas y los ajustes que pide el flujo, y recibe sus resultados como archivos.
Una ejecución puede tardar, así que la API responde de inmediato con una ejecución que se puede seguir.
Crear una
En API Builder, empiece una nueva API y elija «API de flujo». Elija un flujo reutilizable y luego «Crear API».
La página muestra qué envía quien llama y qué recibe. Ambas cosas salen del propio flujo, así que no hay nada que asignar a mano.
Una API de flujo cuenta como una API en su plan. Es un borrador hasta que la publique.
Probarla
En Probar, elige una capa para cada entrada, ajusta los parámetros, elige el formato de cada resultado y selecciona Ejecutar. El flujo se ejecuta ahora, con tu cuenta, sobre los datos de este espacio de trabajo. Cada resultado vuelve como un archivo que puedes descargar. Es la misma solicitud y las mismas comprobaciones que recibe una llamada publicada. Cuenta como una ejecución de flujo y no se publica nada.
Publicarla
Elija «Publicar en Server». La versión publicada conserva exactamente la versión del flujo que usted publicó. Guardar más adelante una versión más reciente del flujo no cambia nada en Server hasta que elija la nueva versión en la página de la API y publique de nuevo.
En la consola de Server, cree una clave para quien llama y dele acceso a la API.
Iniciar una ejecución
Envíe un POST a la dirección /runs de la API, con la clave en un encabezado.
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
}'
Cada entrada es una de estas:
| Enviar | Para |
|---|---|
{"layer_id": "…"} | Una capa que el entorno tiene permiso de leer |
{"geojson": …} | Sus propias entidades, como FeatureCollection de GeoJSON |
{"rows": […]} | Sus propias filas de tabla |
{"area": …} | Un polígono, para una entrada de tipo área |
null | Una entrada opcional que usted omite |
Los datos que envía con una solicitud se usan solo para esa ejecución. Nunca se convierten en una capa del espacio de trabajo. Una solicitud puede llevar hasta 5000 filas para una entrada.
La respuesta es 202, con la ejecución:
{
"run_id": "0c0f3f3e-7f5e-4a55-9c55-3f6b3c0e8f11",
"state": "queued",
"links": { "self": "/public/api/…/runs/0c0f3f3e-…", "cancel": "/public/api/…/runs/0c0f3f3e-…/cancel" }
}
Si algo en la solicitud es incorrecto, la respuesta es 422 y nombra cada campo. No se inicia ninguna ejecución y no se cuenta nada.
Esperar una ejecución corta
Agregue wait_seconds, hasta 60. Si la ejecución termina en ese tiempo, la respuesta es 200, con la ejecución finalizada y sus resultados. Si no, es 202 como antes.
Reintentar sin riesgo
Envíe un encabezado Idempotency-Key. Enviar de nuevo la misma solicitud con la misma clave devuelve la misma ejecución y no inicia una segunda. Usar la clave con una solicitud distinta se rechaza.
Seguir una ejecución y obtener los resultados
| Llamada | Efecto |
|---|---|
GET /runs/{run_id} | Devuelve la ejecución y su estado |
POST /runs/{run_id}/cancel | Cancela una ejecución que no ha terminado |
GET /runs/{run_id}/results/{key} | Devuelve un resultado como archivo |
Una ejecución está queued, running, completed, failed o cancelled. Los resultados solo se muestran cuando ha finalizado correctamente.
Un resultado de tipo capa se devuelve como GeoJSON, o como GeoParquet si lo pide. Una tabla se devuelve como CSV, o como Parquet si lo pide:
{ "formats": { "nearby": "geoparquet" } }
Una ejecución responde solo al consumidor de la clave que la inició. A cualquier otro se le responde que no existe.
Usarla desde un cliente de IA
Con los planes Delivery y Enterprise, una API de flujo puede ofrecerse a clientes de IA como herramienta mediante el Model Context Protocol (MCP).
En la consola de Server, abra la API, vaya a Configuración y active «Disponible para asistentes de IA». «Conectar un cliente de IA» muestra entonces la dirección y la configuración para pegar en el cliente.
El cliente ve una herramienta por cada API de flujo, con las entradas y los ajustes del flujo como argumentos. Una llamada que termina rápido recibe sus resultados. Una más larga recibe un identificador de ejecución, que el cliente completa con las herramientas run_status, run_result y run_cancel.
Qué cuenta una ejecución
Cada ejecución aceptada es una ejecución de ETL del espacio de trabajo propietario de la API, y su duración cuenta como tiempo de procesamiento. Cada llamada cuenta como una solicitud de API. Una llamada rechazada no cuenta como ninguna de las dos.
Cuando se elimina el flujo
Si el flujo de una API de flujo se mueve a la papelera, la página de la API muestra «Fuente en la papelera» y no puede publicarse de nuevo hasta que se restaure el flujo. Tras una eliminación permanente muestra «Necesita una fuente». Lo que ya está en Server sigue activo en ambos casos.