Uso de la API

Integra cualquier agente de IA con TeeckIn mediante la API REST.

Resumen

Esta página cubre la autenticación con credenciales de cliente para herramientas de IA que no admiten OAuth en el navegador (como Cursor, Copilot, Windsurf o integraciones personalizadas).

¿Usas Claude Code?

Claude Code admite OAuth en el navegador con PKCE: no necesitas claves de API ni secretos. Consulta la guía de Configuración de Claude Code en su lugar.

¿Buscas la API versionada y la documentación de Swagger?

Esta página cubre la autenticación de agentes y los endpoints de conveniencia. Para la superficie estable y versionada /api/v1 y la referencia interactiva de Swagger, consulta .

Cuándo usar las credenciales de cliente

Usa las credenciales de cliente (claves de API) cuando tu herramienta de IA:

-No admite OAuth 2.0 con PKCE (autenticación en el navegador)
-Necesita autenticarse de forma no interactiva (CI/CD, scripts, hooks)
-Es una integración personalizada que estás desarrollando tú mismo

Autenticación

La autenticación con credenciales de cliente requiere un Client ID y un de la configuración de tu agente en TeeckIn. Estos se intercambian por un token de acceso de corta duración.

1. Obtén el token de acceso

bash

curl -X POST https://teeckin.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=teeckin_agent_..." \
  -d "client_secret=tcs_..."

Devuelve un token de acceso (válido durante 1 hora):

json

{
  "access_token": "tat_...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Usa el token de acceso

bash

curl https://teeckin.com/api/timer/active \
  -H "Authorization: Bearer tat_..."

Renovación del token

Los tokens de acceso caducan al cabo de 1 hora. Solicita uno nuevo usando las mismas credenciales de cliente. No hay un flujo de token de actualización aparte.

Endpoints sencillos para agentes

Estos endpoints simplificados están pensados para hooks de shell y scripts. Aceptan nombres de temas (con coincidencia aproximada) además de IDs, lo que los hace ideales para los hooks SessionEnd de Claude Code.

GET /api/agent/topics

Lista los temas disponibles. Devuelve una lista plana con los nombres de las categorías.

Respuesta:

{
  "topics": [
    { "id": "top-456", "name": "Project Alpha", "category": "Client Work" },
    { "id": "top-789", "name": "Research", "category": "Internal" }
  ]
}

GET /api/agent/timer

Comprueba el estado del cronómetro.

Respuesta:

{
  "running": true,
  "topic": { "id": "top-456", "name": "Project Alpha", "category": "Client Work" },
  "elapsedMinutes": 45,
  "startedAt": "2026-03-30T10:00:00Z"
}

POST /api/agent/timer/start

Inicia un cronómetro. Acepta el nombre del tema (con coincidencia aproximada) o su ID.

Cuerpo de la solicitud:

{ "topic": "Project Alpha" }

Respuesta:

{
  "started": true,
  "topic": { "id": "top-456", "name": "Project Alpha", "category": "Client Work" }
}

POST /api/agent/timer/stop

Para el cronómetro activo. Perfecto para los hooks SessionEnd.

Respuesta:

{
  "stopped": true,
  "duration": 45,
  "clockedTimeId": "ct-789"
}

POST /api/agent/time

Registra una entrada de tiempo completada sin usar el cronómetro.

Cuerpo de la solicitud:

{
  "topic": "Project Alpha",
  "duration_minutes": 30,
  "notes": "Completed code review"
}

Respuesta:

{
  "logged": true,
  "id": "ct-abc",
  "topic": { "id": "top-456", "name": "Project Alpha", "category": "Client Work" },
  "duration": 30
}

GET /api/agent/tags

Lista las etiquetas disponibles para clasificar las entradas de tiempo.

Respuesta:

{
  "tags": [
    { "id": "tag-123", "name": "bug-fix" },
    { "id": "tag-456", "name": "feature" },
    { "id": "tag-789", "name": "refactoring" }
  ]
}

PATCH /api/agent/timer

Actualiza el cronómetro activo con notas que describen el trabajo.

Cuerpo de la solicitud:

{ "notes": "Implementing user authentication module" }

Respuesta:

{
  "updated": true,
  "clockedTimeId": "ct-789"
}

POST /api/agent/timer/tags

Añade etiquetas al cronómetro activo. Las etiquetas se crean si no existen.

Cuerpo de la solicitud:

{ "tags": ["refactoring", "performance"] }

Respuesta:

{
  "added": true,
  "clockedTimeId": "ct-789",
  "tags": ["refactoring", "performance"]
}

Endpoints completos de la API

Estos son los endpoints completos de la API, con más opciones y respuestas detalladas. Úsalos cuando necesites más control sobre la solicitud.

GET /api/topics/for-agent

Lista los temas disponibles con agrupaciones por categoría y pistas sobre el uso reciente.

Respuesta:

{
  "categories": [
    {
      "id": "cat-123",
      "name": "Client Work",
      "topics": [
        { "id": "top-456", "name": "Project Alpha", "recentlyUsed": true },
        { "id": "top-789", "name": "Research", "recentlyUsed": false }
      ]
    }
  ],
  "recentTopicIds": ["top-456"],
  "defaultTopicId": "top-456",
  "organizationGuidance": "Use Project Alpha for client deliverables..."
}

POST /api/timer/start

Inicia un cronómetro en un tema concreto.

Cuerpo de la solicitud:

{ "topicId": "top-456" }

Respuesta:

{
  "clockedTime": {
    "id": "ct-789",
    "topicId": "top-456",
    "startTime": "2026-03-30T10:00:00Z"
  }
}

POST /api/timer/stop

Para el cronómetro activo. Opcionalmente, añade notas.

Cuerpo de la solicitud:

{ "notes": "Completed competitor analysis" }

Respuesta:

{
  "clockedTime": {
    "id": "ct-789",
    "startTime": "2026-03-30T10:00:00Z",
    "endTime": "2026-03-30T10:45:00Z"
  }
}

GET /api/timer/active

Comprueba si hay un cronómetro en marcha.

Respuesta:

{
  "active": true,
  "clockedTime": {
    "id": "ct-789",
    "topicId": "top-456",
    "startTime": "2026-03-30T10:00:00Z"
  }
}

POST /api/clocked-times

Crea una entrada de tiempo manual (para registro retroactivo).

Cuerpo de la solicitud:

{
  "topicId": "top-456",
  "startTime": "2026-03-30T09:00:00Z",
  "endTime": "2026-03-30T10:30:00Z",
  "type": "manual",
  "notes": "Drafted quarterly report"
}

Respuesta:

{
  "id": "ct-abc",
  "topicId": "top-456",
  "startTime": "2026-03-30T09:00:00Z",
  "endTime": "2026-03-30T10:30:00Z"
}

Límites de uso

Las llamadas a la API de agentes tienen límites de uso para evitar abusos:

Operación	Límite
Lectura (GET)	120 por minuto
Escritura (POST/PATCH)	30 por minuto
Operaciones del cronómetro	10 por minuto

Cabeceras de límite de uso

Consulta la cabecera X-RateLimit-Remaining en las respuestas para controlar tu uso.

Respuestas de error

Códigos de error habituales que puedes encontrar:

401

Token de acceso no válido o caducado

Solicita un nuevo token usando tus credenciales de cliente

403

Agente desactivado o secreto revocado

Comprueba el estado del agente en Configuración > Agentes

404

Tema no encontrado

Usa /api/topics/for-agent para obtener IDs válidos

429

Límite de uso superado

Espera y reinténtalo cuando se restablezca el límite

Buenas prácticas

1.Almacena en caché la lista de temas y actualízala solo cuando sea necesario
2.Para siempre los cronómetros cuando termine el trabajo
3.Incluye notas significativas que describan lo que se hizo
4.Gestiona los límites de uso con elegancia mediante retroceso exponencial
5.Guarda los client secrets de forma segura y mantén los archivos de configuración fuera de git
6.Rota los secretos periódicamente desde Configuración > Agentes > pestaña Secretos