Utilisation de l'API

Intégrez n'importe quel agent IA à TeeckIn via l'API REST.

Présentation

Cette page traite de l'authentification par identifiants client pour les outils d'IA qui ne prennent pas en charge l'OAuth dans le navigateur (comme Cursor, Copilot, Windsurf ou les intégrations personnalisées).

Vous utilisez Claude Code ?

Claude Code prend en charge l'OAuth dans le navigateur avec PKCE : vous n'avez besoin ni de clés d'API ni de secrets. Consultez plutôt le guide de Configuration de Claude Code.

Vous cherchez l'API versionnée et la documentation Swagger ?

Cette page traite de l'authentification des agents et des endpoints pratiques. Pour la surface stable et versionnée /api/v1 et la référence Swagger interactive, consultez .

Quand utiliser les identifiants client

Utilisez les identifiants client (clés d'API) lorsque votre outil d'IA :

-Ne prend pas en charge OAuth 2.0 avec PKCE (authentification dans le navigateur)
-Doit s'authentifier de façon non interactive (CI/CD, scripts, hooks)
-Est une intégration personnalisée que vous développez vous-même

Authentification

L'authentification par identifiants client nécessite un Client ID et un issus des paramètres de votre agent dans TeeckIn. Ils sont échangés contre un jeton d'accès de courte durée.

1. Obtenir le jeton d'accès

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_..."

Renvoie un jeton d'accès (valable 1 heure) :

json

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

2. Utiliser le jeton d'accès

bash

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

Renouvellement du jeton

Les jetons d'accès expirent au bout d'1 heure. Demandez-en un nouveau avec les mêmes identifiants client. Il n'existe pas de flux distinct de jeton de rafraîchissement.

Endpoints simples pour les agents

Ces endpoints simplifiés sont conçus pour les hooks de shell et les scripts. Ils acceptent les noms de Topics (avec correspondance approximative) en plus des IDs, ce qui les rend idéaux pour les hooks SessionEnd de Claude Code.

GET /api/agent/topics

Liste les Topics disponibles. Renvoie une liste à plat avec les noms de catégories.

Réponse :

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

GET /api/agent/timer

Vérifie l'état du Timer.

Réponse :

{
  "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

Démarre un Timer. Accepte le nom du Topic (avec correspondance approximative) ou son ID.

Corps de la requête :

{ "topic": "Project Alpha" }

Réponse :

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

POST /api/agent/timer/stop

Arrête le Timer actif. Parfait pour les hooks SessionEnd.

Réponse :

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

POST /api/agent/time

Enregistre un pointage terminé sans utiliser le Timer.

Corps de la requête :

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

Réponse :

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

GET /api/agent/tags

Liste les tags disponibles pour classer les pointages.

Réponse :

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

PATCH /api/agent/timer

Met à jour le Timer actif avec des notes décrivant le travail.

Corps de la requête :

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

Réponse :

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

POST /api/agent/timer/tags

Ajoute des tags au Timer actif. Les tags sont créés s'ils n'existent pas.

Corps de la requête :

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

Réponse :

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

Endpoints complets de l'API

Voici les endpoints complets de l'API, avec davantage d'options et des réponses détaillées. Utilisez-les lorsque vous avez besoin de plus de contrôle sur la requête.

GET /api/topics/for-agent

Liste les Topics disponibles avec des regroupements par catégorie et des indications sur l'usage récent.

Réponse :

{
  "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

Démarre un Timer sur un Topic précis.

Corps de la requête :

{ "topicId": "top-456" }

Réponse :

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

POST /api/timer/stop

Arrête le Timer actif. Vous pouvez éventuellement ajouter des notes.

Corps de la requête :

{ "notes": "Completed competitor analysis" }

Réponse :

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

GET /api/timer/active

Vérifie s'il y a un Timer en cours.

Réponse :

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

POST /api/clocked-times

Crée un pointage manuel (pour un enregistrement rétroactif).

Corps de la requête :

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

Réponse :

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

Limites de débit

Les appels à l'API des agents sont soumis à des limites de débit pour prévenir les abus :

Opération	Limite
Lecture (GET)	120 par minute
Écriture (POST/PATCH)	30 par minute
Opérations du Timer	10 par minute

En-têtes de limite de débit

Consultez l'en-tête X-RateLimit-Remaining dans les réponses pour surveiller votre utilisation.

Réponses d'erreur

Codes d'erreur courants que vous pouvez rencontrer :

401

Jeton d'accès invalide ou expiré

Demandez un nouveau jeton avec vos identifiants client

403

Agent désactivé ou secret révoqué

Vérifiez l'état de l'agent dans Paramètres > Agents

404

Topic introuvable

Utilisez /api/topics/for-agent pour obtenir des IDs valides

429

Limite de débit dépassée

Patientez et réessayez une fois la limite réinitialisée

Bonnes pratiques

1.Mettez en cache la liste des Topics et ne l'actualisez qu'au besoin
2.Arrêtez toujours les Timers lorsque le travail est terminé
3.Incluez des notes pertinentes décrivant ce qui a été fait
4.Gérez les limites de débit avec élégance grâce à un backoff exponentiel
5.Stockez les client secrets en toute sécurité et gardez les fichiers de configuration hors de git
6.Faites tourner les secrets régulièrement via Paramètres > Agents > onglet Secrets