--- title: Activar una rutina a través de la API url: https://platform.claude.com/docs/es/api/claude-code/routines-fire description: Inicia una sesión de rutina de Claude Code bajo demanda enviando una solicitud POST autenticada. --- Esta es una API experimental. La estructura de las solicitudes y respuestas, los "rate limits" (límites de velocidad) y la semántica de los tokens podrían cambiar. [Claude Code](https://code.claude.com/docs) es la herramienta de codificación agéntica de Anthropic. [Claude Code en la web](https://code.claude.com/docs/es/claude-code-on-the-web) ejecuta sesiones de Claude Code en infraestructura en la nube administrada por Anthropic en claude.ai/code, y una [rutina](https://code.claude.com/docs/en/routines) ("routine") es una configuración guardada allí: un prompt, uno o más repositorios y conectores, empaquetados para que pueda ejecutarse sin supervisión según un horario, en respuesta a eventos de GitHub o cuando se invoca por HTTP. Este endpoint es el punto de entrada HTTP. Hacer un POST a él inicia una nueva ejecución de una rutina existente y devuelve el ID y la URL de la sesión resultante. Quienes suelen llamarlo son sistemas de alertas, pipelines de CI y herramientas internas que necesitan iniciar una sesión de Claude Code de forma programática. Llamar a este endpoint requiere una cuenta de claude.ai en un plan Pro, Max, Team o Enterprise con [Claude Code en la web](https://code.claude.com/docs/es/claude-code-on-the-web) habilitado. Autentícate con un "bearer token" (token de portador) por rutina creado en la interfaz web de Claude Code en lugar de una clave de API de Claude. ## Diferencias con Claude Platform El endpoint de activación de rutinas pertenece a la superficie de producto de Claude Code, que difiere de las APIs y SDKs de Claude Platform en algunos aspectos: | Aspecto | Este endpoint | APIs de Claude Platform | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Autenticación | `Authorization: Bearer` con un token por rutina (`sk-ant-oat01-...`) creado en [claude.ai/code/routines](https://claude.ai/code/routines) | `x-api-key` con una clave de API de Claude obtenida en Claude Console | | Alcance del token | Solo una rutina; sin acceso de lectura | A nivel de espacio de trabajo | | Soporte de SDK | Ninguno | Disponible en todos los [SDKs de cliente](https://platform.claude.com/docs/es/cli-sdks-libraries/overview) | | Facturación | Uso de la suscripción de Claude Code en claude.ai | Uso de Claude Platform | | Espacio de nombres de la ruta | `/v1/claude_code/...` | `/v1/...` | | Estabilidad | Experimental | Estable o beta estándar | ## Antes de comenzar Para llamar a este endpoint, necesitas: 1. Una rutina creada en [claude.ai/code/routines](https://claude.ai/code/routines). 2. Un bearer token generado para esa rutina: abre la rutina para editarla, haz clic en **Add another trigger** debajo de **Select a trigger**, elige **API** y luego haz clic en **Generate token** en la ventana modal. El token se muestra una sola vez y no se puede recuperar después. Consulta [Agregar un disparador de API](https://code.claude.com/docs/en/routines#add-an-api-trigger) en la documentación de Claude Code para ver la guía completa de configuración. ## Activar una rutina ```http POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire ``` La interfaz web de Claude Code proporciona la URL completa junto con el token cuando agregas un disparador de API, por lo que la mayoría de las integraciones almacenan ambos como secretos y llaman al endpoint directamente. Los siguientes ejemplos muestran una llamada desde la shell y un paso de GitHub Actions que activa la rutina cuando falla la CI. ```bash cURL curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \ -H "Authorization: Bearer $ROUTINE_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}' ``` ```yaml GitHub Actions - if: failure() env: ROUTINE_FIRE_URL: ${{ secrets.ROUTINE_FIRE_URL }} ROUTINE_FIRE_TOKEN: ${{ secrets.ROUTINE_FIRE_TOKEN }} run: | curl -X POST "$ROUTINE_FIRE_URL" \ -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d "{\"text\": \"CI failed: $GITHUB_WORKFLOW run $GITHUB_RUN_ID on $GITHUB_REF\"}" ``` La solicitud retorna una vez que se crea la sesión. No hace streaming de la salida de la sesión ni espera a que la sesión se complete. ### Encabezados | Nombre | Requerido | Descripción | | ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Sí | `Bearer `. El token por rutina creado en la interfaz web de Claude Code, con el prefijo `sk-ant-oat01-`. | | `anthropic-version` | Sí | La [versión de la API](https://platform.claude.com/docs/es/api/versioning). `2023-06-01` es el único valor aceptado. | | `Content-Type` | Cuando hay cuerpo | `application/json`. | Las integraciones anteriores que envían un encabezado `anthropic-beta: experimental-cc-routine-2026-04-01` no se ven afectadas: el endpoint acepta solicitudes con y sin él. ### Parámetros de ruta | Nombre | Tipo | Descripción | | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `routine_id` | string | El identificador de la rutina. A pesar del nombre del parámetro, el valor tiene el prefijo `trig_` en lugar de `routine_`. Se incluye en la URL que muestra la ventana modal cuando agregas un disparador de API. | ### Cuerpo de la solicitud | Campo | Tipo | Requerido | Descripción | | ------ | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | No | Contexto inicial para esta ejecución, como el cuerpo de una alerta, una línea de log con fallos o un git diff. El valor es texto libre y no se analiza; si envías JSON u otra carga estructurada, la rutina lo recibe como una cadena literal. Se pasa a la rutina junto con su prompt guardado. Máximo 65,536 caracteres. | El cuerpo es opcional. Los campos desconocidos en el cuerpo se ignoran. ### Respuesta Una solicitud exitosa devuelve `200 OK` con los detalles de la nueva sesión: ```json { "type": "routine_fire", "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ", "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } ``` | Campo | Tipo | Descripción | | ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Siempre `routine_fire`. | | `claude_code_session_id` | string | El ID de la sesión de Claude Code creada para esta ejecución. | | `claude_code_session_url` | string | Un enlace a la sesión en claude.ai. Ábrelo en un navegador para observar la ejecución, revisar los cambios o continuar la conversación. | ### Errores Los errores usan el [sobre de error](https://platform.claude.com/docs/es/api/errors) estándar de Anthropic: ```json { "type": "error", "error": { "type": "not_found_error", "message": "" } } ``` | Estado HTTP | Tipo de error | Causa | | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | Falta el encabezado `anthropic-version` o su valor no es compatible, `text` supera los 65,536 caracteres, o la rutina está en pausa (consulta [Editar y controlar rutinas](https://code.claude.com/docs/en/routines#edit-and-control-routines)). | | 401 | `authentication_error` | No hay un bearer token en el encabezado `Authorization`, o el token no corresponde a esta rutina. | | 403 | `permission_error` | La cuenta u organización no tiene acceso a este endpoint. | | 404 | `not_found_error` | La rutina no existe. | | 429 | `rate_limit_error` | Se alcanzó un límite de activaciones por hora para la rutina o para la cuenta. La respuesta incluye un encabezado `Retry-After` que indica cuándo se restablece la ventana. | | 500 | `api_error` | Un error inesperado del servidor. Reintenta con "exponential backoff" (retroceso exponencial). Si el error persiste, contacta al soporte con el ID de la solicitud. | | 503 | `overloaded_error` | El servicio está sobrecargado temporalmente. Reintenta después de una breve espera. Claude Platform devuelve 529 para este tipo de error, mientras que este endpoint devuelve 503. | ## Autenticación El bearer token tiene alcance sobre una sola rutina. Un token comprometido solo puede activar esa rutina; no otorga acceso de lectura, ni acceso a otras rutinas, ni acceso a los datos de la cuenta. Genera y revoca tokens desde la configuración del disparador de API de la rutina en [claude.ai/code/routines](https://claude.ai/code/routines). No existe una API pública para la gestión de tokens. Generar un nuevo token revoca el anterior. ## Idempotencia Cada solicitud exitosa crea una nueva sesión. No hay clave de idempotencia. Si un webhook que llama al endpoint reintenta, el endpoint crea múltiples sesiones. ## Límites de velocidad Las activaciones por API tienen un límite por hora. Cada rutina acepta hasta 30 activaciones por hora, un límite compartido entre las activaciones por API, el botón **Run now** de la interfaz web y las reactivaciones de ejecución única. Además, cada cuenta puede realizar hasta 100 activaciones por API por hora entre todas sus rutinas. Las sesiones resultantes consumen el mismo uso de la suscripción de Claude Code que las sesiones interactivas. Cuando se alcanza un límite, el endpoint devuelve `429 rate_limit_error` con un encabezado `Retry-After`. Para saber cómo interactúa el uso de las rutinas con los límites de la suscripción y la facturación por uso adicional, consulta [Uso y límites](https://code.claude.com/docs/en/routines#usage-and-limits) en la documentación de Claude Code. ## Soporte de SDK Este endpoint no está en los SDKs de Anthropic. Su modelo de tokens difiere de la autenticación con clave de API, y quienes suelen llamarlo, como trabajos de CI y webhooks de alertas, envían la solicitud directamente. ## Ver también * [Automatizar el trabajo con rutinas](https://code.claude.com/docs/en/routines) en la documentación de Claude Code * [Errores](https://platform.claude.com/docs/es/api/errors)