Crear un run
post /v1/runs
Crea un run: la primitiva única de Klevy. Un run es (flujo, credencial, parámetros) y devuelve un resultado normalizado, sus documentos y un evento de uso.
Responde
200 si el run alcanzó a terminar dentro de wait_ms, y 202 si sigue en la cola — en ese caso el resultado llega por webhook.Con
Idempotency-Key, reintentar devuelve el run existente: no crea otro ni factura de nuevo. Úsala siempre que el reintento pueda venir de una red inestable.Si el flujo exige clave del titular (
credential: CU o CT) y no tienes un credential_ref, no uses este endpoint: abre una sesión de widget.Autenticación
Requiere API key (sk_live_… · sk_test_…) en la cabecera
authorization: Bearer …. Ver autenticación.
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
Idempotency-Key | header | string | Reintentar con la misma clave devuelve el run existente; no crea otro ni factura de nuevo. |
Cuerpo de la petición
flow string obligatorio
params object
Por omisión: {}
credential_ref string
rut string
execution_token string
wait_ms integer
metadata object
Respuesta 200
Run terminado dentro de wait_ms
run_id string obligatorio
flow string obligatorio
flow_version integer obligatorio
status enum obligatorio
queuedrunningawaiting_confirmationsucceededfailedexpiredcancelled
data object | null obligatorio
document object | null obligatorio
type enum obligatorio
pdfjsonscreenshothtml
download_url string obligatorio
expires_at string obligatorio
sha256 string obligatorio
bytes integer obligatorio
documents object[]
Por omisión: []
type enum obligatorio
pdfjsonscreenshothtml
download_url string obligatorio
expires_at string obligatorio
sha256 string obligatorio
bytes integer obligatorio
source_meta object | null obligatorio
driver string obligatorio
obtained_at string obligatorio
portal string obligatorio
portal_ref string
duration_ms integer
attempts integer
error object | null obligatorio
code enum obligatorio
invalid_paramscredential_invalidcredential_expiredportal_unavailableportal_changednot_foundrate_limitedflow_disabledinternal_errorauthentication_errorpermission_deniedconflict
message string obligatorio
execution_token string
execution_token_expires_at string
session_id string | null
parent_run_id string | null
created_at string obligatorio
finished_at string | null obligatorio
Errores
| Código | Cuándo |
|---|---|
400 | Parámetros inválidos |
401 | API key inválida |
409 | Flujo deshabilitado o conflicto de idempotencia |
El cuerpo de cualquier error sigue la misma forma y su code viene de un
catálogo cerrado. Ver errores.