# API

> La API de tu Orkan: cómo autenticarte con una clave, qué áreas ofrece y ejemplos con curl.

Todo lo que haces en la interfaz de Orkan también se puede hacer por su API: listar y activar automatizaciones, lanzarlas, consultar ejecuciones, gestionar cuentas… Sirve para conectar Orkan con tus propios programas.

> **La API todavía puede cambiar**
>
> La API todavía puede cambiar
> 
> La API está en la **versión 0.0.0**: sus rutas y respuestas pueden cambiar sin aviso mientras Orkan sigue en desarrollo. No construyas nada crítico sobre ella sin hablar antes con nosotros.

## Dónde está

En tu Orkan, bajo `/v1/`:

```text
https://<tu-espacio>.itsorkan.com/v1/
```

Si tienes Orkan en tus servidores, es la dirección pública que hayas configurado (`public_url`).

## Autenticarte

La API acepta dos formas:

-   **Clave de API** (`ok_…`), para programas. Va en la cabecera `Authorization: Bearer`.
-   **Cookie de sesión**, que es la que usa la propia interfaz al iniciar sesión.

Para crear una clave, activa el **Modo avanzado** en **Ajustes › Avanzado** y entra en **Personas y accesos**:

-   **Mis tokens › Crear token**: una clave personal para que un programa actúe **en tu nombre**. Nunca puede hacer más de lo que puedes hacer tú. Elige un nombre, los permisos (**Solo mirar**, **Mirar y lanzar**, **Crear y cambiar automatizaciones** o **Elegir uno a uno**) y, si quieres, una fecha de caducidad.
-   **Cuentas de servicio › Crear cuenta de servicio**: una «persona» para programas, sin la cuenta de nadie. Tiene sus claves y un límite de peticiones por minuto.

> **La clave se muestra una sola vez**
>
> La clave se muestra una sola vez
> 
> Cópiala al crearla («Cópialo ahora»). No volverá a mostrarse. Nunca la pegues en un chat, un repositorio ni una página web; si se filtra, **Revocar** la clave.

## Ejemplos

Pon tu dirección y tu clave en variables de entorno, sin escribirlas en comandos que guardes:

```bash
export ORKAN_URL="https://<tu-espacio>.itsorkan.com"
export ORKAN_KEY="<tu clave ok_…>"
```

Saber en qué proyectos puedes trabajar:

```bash
curl -s "$ORKAN_URL/v1/projects" \
  -H "Authorization: Bearer $ORKAN_KEY"
```

Devuelve la lista de tus proyectos, cada uno con su `id`, `organization_id`, `name` y `created_at`. Usa el `id` como `<project_id>` en las demás rutas.

Listar las automatizaciones de un proyecto:

```bash
curl -s "$ORKAN_URL/v1/projects/<project_id>/workflows" \
  -H "Authorization: Bearer $ORKAN_KEY"
```

Responde con `items` y, si hay más, `next_cursor`.

## Áreas

| Área | Rutas |
| --- | --- |
| **Tú** | `GET /v1/me` |
| **Proyectos** | `GET /v1/projects`, `GET /v1/projects/{project_id}` |
| **Automatizaciones** | `/v1/projects/{project_id}/workflows…`: crear, ver, cambiar, `…/draft`, `…/publications`, `…/export` y `/workflows/import` |
| **Activación** | `PUT` y `DELETE /v1/projects/{project_id}/workflows/{workflow_id}/activation` activan y pausan |
| **Lanzar** | `POST …/workflows/{workflow_id}/runs` |
| **Ejecuciones** | `/v1/projects/{project_id}/runs…`: listar, ver detalle, registros, historial, `…/cancel` (detener) y `…/retry` (volver a ejecutar) |
| **Cuentas conectadas** | `/v1/credentials…`: crear, probar, revocar y compartir |
| **Módulos** | Integraciones instaladas y catálogo |
| **Avisos a otros sistemas** | `/v1/admin-webhooks`: suscripciones a eventos de administración y sus entregas |
| **Asistentes y MCP** | Mira [MCP](https://wiki.itsorkan.com/ia/mcp/) |

Todas las rutas comprueban tus permisos: una clave solo puede hacer lo que su rol y sus permisos permiten. Lo que hace cada clave queda en **Actividad**.

## El fichero OpenAPI

La descripción completa de la API (259 rutas) está en un fichero OpenAPI que no se publica en esta wiki. **Pídelo si lo necesitas**: [contact@gnevoo.es](mailto:contact@gnevoo.es).

## Límites

-   Hay límites de peticiones; si te pasas, la API responde que esperes un momento y vuelvas a probar.
-   Los errores devuelven un JSON con la causa. Las respuestas `401` y `403` significan, respectivamente, clave inválida o sin permiso.