Usar la API de AI Tasker sin SDK

No todo agente puede cargar un cliente MCP: algunos solo tienen un runtime con fetch, un workflow sin dependencias o un script que corre en un cron. Para eso está la API HTTP, que comparte workspace, credenciales y cuotas con MCP. Esta guía es el mínimo viable: autenticarse bien, escribir sin duplicar, paginar sin perder registros y distinguir un error que se reintenta de uno que no.

Autenticación: tres formas, una identidad

La API acepta tres credenciales distintas y las tres acaban en el mismo sitio: un userId y, si es una clave, el workspace al que pertenece.

Sin ninguna de las tres, la respuesta es 401 UNAUTHENTICATED.
Cabecera	Para quién	Nota
`Authorization: Bearer atkr_...`	Agentes y CLIs	La misma clave que usa MCP
`x-api-key: atkr_...`	Clientes que no pueden tocar `Authorization`	Mismo efecto; útil en workflows con cabeceras gestionadas
`Authorization: Bearer <JWT de Clerk>`	El dashboard	Sesión humana; no la uses en un agente

La identidad sale de la credencial, no de un parámetro. Si mandas un workspaceId que no está en los workspaces de tu clave, recibes un error de acceso aunque el identificador exista: es el perímetro haciendo su trabajo.

Leer sin SDK: la llamada más simple

Proyectos del workspace de la clave.

curl -s https://api.ai-tasker.theboomer.dev/api/projects \
  -H "x-api-key: atkr_tu_clave"

# En Python es identico:
# requests.get(url, headers={"x-api-key": "atkr_..."})
# En Node:  fetch(url, { headers: { "x-api-key": "atkr_..." } })

Las lecturas cuestan una operación de agente (AGENT_READ), igual que una mutación cuesta la misma unidad. Lo que no cuesta nada es la lectura humana en el dashboard: si estás construyendo un panel para personas, esa vía no consume cupo de agente.

Escribir sin duplicar: Idempotency-Key

Crear una tarea por API exige la cabecera Idempotency-Key, entre 16 y 160 caracteres. Sin ella, o con una más corta, la respuesta es 400 IDEMPOTENCY_KEY_REQUIRED. No es un capricho: un agente que reintenta tras un timeout duplicaría la tarea si la clave no fuese la misma.

Un identificador estable por intención de escritura, no por intento.

KEY=$(python3 -c "import uuid;print(uuid.uuid4())")

curl -s -X POST https://api.ai-tasker.theboomer.dev/api/tasks \
  -H "x-api-key: atkr_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{
    "projectId": "ID_DEL_PROYECTO",
    "title": "Revisar los webhooks caidos",
    "description": "Comprobar las entregas fallidas de las ultimas 24 h"
  }'

La misma clave con el mismo cuerpo devuelve el mismo resultado, no una segunda tarea. Si cambias el cuerpo y reutilizas la clave, el servidor lo detecta y responde con un conflicto: es la señal de que estabas reutilizando un identificador que no tocaba.

Paginar por cursor sin perder registros

GET /api/tasks no pagina por número de página, pagina por cursor. Eso evita el clásico problema de saltarse registros cuando algo se crea mientras recorres la lista.

La respuesta trae hasMore y nextCursor; se repite hasta que hasMore sea false.

curl -s "https://api.ai-tasker.theboomer.dev/api/tasks?limit=50&sort=createdAt&order=desc" \
  -H "x-api-key: atkr_tu_clave"

# { "tasks": [...], "hasMore": true, "nextCursor": {...}, "limit": 50, "sort": "createdAt", "order": "desc" }
#
# Siguiente pagina: mismo endpoint con &cursor=<nextCursor serializado>

No guardes el cursor como texto opaco y lo reconstruyas a mano: envíalo tal como viene en nextCursor, serializado, y deja que el servidor lo interprete.

Qué error se reintenta y cuál no

Errores medidos en el código de las rutas y en el middleware de identidad.
Respuesta	Significado	Acción
`400 IDEMPOTENCY_KEY_REQUIRED`	Falta la cabecera o mide menos de 16 caracteres	Generar una clave estable por intención; no reintentar igual
`400 title is required` / `projectId is required`	Falta un campo obligatorio del cuerpo	Corregir el cuerpo
`401 UNAUTHENTICATED`	No hay credencial válida	Añadir `x-api-key` o `Bearer atkr_...`
`403 WORKSPACE_ARCHIVED`	El workspace se archivó por inactividad (ciclo 7+7)	Que un humano lo reclame o lo reactive; no reintentar
`429 OPERATION_QUOTA_EXCEEDED`	Cupo mensual del workspace agotado	Ampliar con créditos (acción humana) o esperar
`429 AGENT_DAILY_REQUEST_QUOTA_EXCEEDED`	Guarda diaria anti-abuso	Esperar a las 00:00 UTC
`503` con reembolso	Fallo de plataforma	Reintentar: la operación no se cobra y el cargo se devuelve

La regla general: los 4xx son tuyos y se arreglan cambiando la petición; los 5xx son de la plataforma, se reintentan con espera creciente y no se facturan. Reintentar un 400 mil veces solo gasta tiempo y ensucia las métricas.

Mapa mínimo de endpoints

El contrato completo está en /api/openapi.json; esta tabla es el arranque.
Recurso	Endpoints útiles
Proyectos	`GET /api/projects` · `POST /api/projects`
Tareas	`GET /api/tasks` (cursor) · `POST /api/tasks` (idempotente) · `PATCH /api/tasks/:id`
Sprints	`GET /api/sprints` · `POST /api/sprints`
Uso y cuotas	`GET /api/usage?period=YYYY-MM` · `GET /api/apikeys/:id/usage`
Monedero	`GET /api/credits/balance` · `GET /api/credits/packs` · `GET /api/credits/history`
Contrato	`GET /api/openapi.json` (público, sin clave)

Antes de escribir tu propio cliente

Lee GET /api/openapi.json en vez de deducir campos del ejemplo de esta página: es público y no necesita clave.
Prueba primero contra list_projects: un 200 con la lista vacía confirma credencial y workspace.
Genera la Idempotency-Key una vez por intención y guárdala si el proceso puede morir a mitad.
No metas la clave en la URL ni en logs: va en cabecera y se trata como un secreto.
Pon un tope de reintentos con espera creciente solo para 5xx; para 429 usa resetAt del cuerpo.
Cierra el agente con DELETE /api/apikeys/:id cuando el trabajo termine: una clave viva es un consumidor vivo.

Llamar a la API de AI Tasker sin SDK

Autenticarse con una API key, crear una tarea idempotente, paginar por cursor y tratar cada error como toca.

Consigue la clave
Crea una API key atkr_ en el dashboard, en el workspace donde va a operar el agente.
Comprueba la identidad
Llama a GET /api/projects con x-api-key: si responde 200, la clave y el workspace están bien.
Crea con idempotencia
POST /api/tasks con Idempotency-Key de 16 a 160 caracteres; repite con la misma clave si hubo timeout.
Pagina con cursor
Recorre GET /api/tasks con limit y nextCursor hasta que hasMore sea false.
Trata los errores por clase
4xx: corrige la petición. 429: espera o amplía créditos. 5xx: reintenta, no se cobra.

Preguntas frecuentes

¿Puedo usar la API sin MCP?

Sí. Comparten workspace, credenciales y cuotas: la API HTTP cubre los mismos recursos y es la vía para runtimes que no pueden cargar un cliente MCP.

¿Cuánto tiene que medir la Idempotency-Key?

Entre 16 y 160 caracteres. Por debajo de 16 la respuesta es 400 IDEMPOTENCY_KEY_REQUIRED, que parece un problema de cabecera ausente y en realidad es de longitud.

¿Cómo sé la versión del contrato?

Leyendo GET /api/openapi.json, que es público y se sirve desde el propio backend. La versión del producto aparece además en /health y en la meta de la web.

¿La API pagina por offset?

No. GET /api/tasks usa cursor: devuelve hasMore y nextCursor, y se recorre repitiendo la llamada con ese cursor.

¿Los reintentos se cobran?

Un fallo de plataforma devuelve 503 con reembolso y la operación no se cobra; el reintento de un 5xx tampoco. Los 4xx no se cobran porque no llegan a ejecutarse.

¿Puedo usar la misma clave en dos agentes?

Puedes, pero comparten revocación y rastro de uso. Una clave por agente hace que cortar uno no afecte a los demás.

Fuentes

Contrato OpenAPI (público)
https://api.ai-tasker.theboomer.dev/api/openapi.json
Planes, límites y operaciones
https://api.ai-tasker.theboomer.dev/api/plans
Información de servicio del agente
https://api.ai-tasker.theboomer.dev/agent/service-info

Cifras verificadas contra la API en vivo y las páginas oficiales de cada producto el 21 de octubre de 2026. Los precios de terceros pueden cambiar: contrasta con la página oficial antes de publicar.

Guías relacionadas

Todas las guías — Cómo elegir gestor de tareas, MCP y ciclo de vida para agentes de IA.
MCP o API HTTP: cuándo usar cada uno — MCP o API HTTP: qué resuelve cada acceso, cuándo usar cada uno y cómo decidir sin duplicar integraciones. Configuración copiable y coste real.
Presupuesto y cuotas por agente — Cómo repartir créditos y cuotas entre varios workspaces y agentes en AI Tasker: qué devuelve cada muro, cómo leer el consumo y cómo cortar el gasto.
Monedero de créditos: recarga y control de gasto — Cómo funciona el monedero de AI Tasker: qué operación consume cada crédito, cómo recargar con packs o AutoRefill, y qué pasa cuando el saldo llega a cero.
Conectar cualquier cliente MCP por HTTP — Handshake MCP completo contra AI Tasker con curl: initialize, cabecera mcp-session-id, tools/list y tools/call, sin SDK y sin framework.
Precios — Precios reales: plan gratuito y unidad facturable de 2,00 €/mes.
Integración MCP — https://mcp.ai-tasker.theboomer.dev/mcp
/llms.txt — Contrato legible por máquina.

Esta guía existe para ser indexada y citada. No está en el menú a propósito.