Activar una rutina a través de la API

Claude Code es la herramienta de codificación agéntica de Anthropic. Claude Code en la web ejecuta sesiones de Claude Code en infraestructura en la nube administrada por Anthropic en claude.ai/code, y una rutina ("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 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:

Antes de comenzar

Para llamar a este endpoint, necesitas:

1. Una rutina creada en 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 en la documentación de Claude Code para ver la guía completa de configuración.

Activar una rutina

POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire

Cada solicitud debe incluir el encabezado anthropic-beta: experimental-cc-routine-2026-04-01. Las solicitudes que no lo incluyan devuelven 400 invalid_request_error.

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.

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 "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'

- 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 "anthropic-beta: experimental-cc-routine-2026-04-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

Parámetros de ruta

Cuerpo de la solicitud

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:

{
  "type": "routine_fire",
  "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
  "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}

Errores

Los errores usan el sobre de error estándar de Anthropic:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "<string>"
  }
}

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. 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 ejecuciones de rutinas cuentan contra una asignación diaria por cuenta que varía según el plan, y las sesiones resultantes consumen el mismo uso de la suscripción de Claude Code que las sesiones interactivas. Cuando se alcanza cualquiera de los dos límites, el endpoint devuelve 429 rate_limit_error con un encabezado Retry-After. Las organizaciones con uso adicional habilitado continúan más allá de la asignación incluida con excedente medido.

Consulta tus ejecuciones diarias restantes en claude.ai/code/routines. Para saber cómo interactúa el uso de rutinas con los límites de la suscripción y la facturación del uso adicional, consulta Uso y límites 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

• Automatiza el trabajo con rutinas en la documentación de Claude Code
• Encabezados beta
• Errores