API Contexts & Assets

Référence complète des points de terminaison REST API des contexts (documents de connaissance versionnés), skills (comportements d’agent multi-fichiers), commands (commandes IA mono-fichier) et scripts (automatisation exécutable) dans CodeCourier.

14 min lire
apicontextsskills

Le système d’assets de CodeCourier fournit un stockage structuré et versionné pour la connaissance et la configuration de comportement utilisées par les agents IA au runtime. Il existe quatre types d’assets :

  • Contexts - Documents de connaissance de projet réutilisables (guides d’architecture, standards de code, règles métier) injectés dans les prompts des agents. Chaque context maintient un historique de versions complet ; seule la version active est servie aux agents.
  • Skills - Bundles multi-fichiers qui étendent les capacités d’un agent. Les skills contiennent des fragments de prompt, du code exemple et des instructions regroupés en un package nommé et versionné.
  • Commands - Ensembles d’instructions en langage naturel mono-fichier qu’un agent peut invoquer par nom, similaire à une macro réutilisable ou une slash command.
  • Scripts - Scripts shell ou Python exécutables qui s’exécutent dans l’environnement sandbox. Les scripts sont versionnés et peuvent être publiés indépendamment de la configuration du workflow.

Tous les types d’assets suivent le même modèle de publication versionnée : vous mettez à jour un asset pour préparer des changements, puis vous publiez pour créer une nouvelle version immuable et l’activer. Les versions précédentes restent accessibles et peuvent être réactivées à tout moment.

Contexts

Objet Context

json
{
  "id": "ctx_...",
  "name": "Architecture Guide",
  "description": "Project architecture and coding standards",
  "activeVersion": {
    "version": 3,
    "content": "# Architecture\n\nThis project uses...",
    "publishedAt": "2024-01-15T10:00:00Z",
    "publishedBy": "user_..."
  },
  "createdAt": "2024-01-01T00:00:00Z"
}
  • id (string) - Identifiant unique du context, préfixé par ctx_
  • name (string) - Nom lisible du context affiché dans le dashboard et injecté comme en-tête dans les prompts des agents
  • description (string) - Résumé bref de ce que contient ce context ; non injecté dans les prompts des agents
  • activeVersion (object | null) - La version actuellement active servie aux agents ; null si aucune version n’a jamais été publiée
  • activeVersion.version (number) - Numéro de version croissant de façon monotone
  • activeVersion.content (string) - Le contenu Markdown ou texte brut complet de cette version
  • activeVersion.publishedAt (timestamp ISO) - Quand cette version a été publiée
  • activeVersion.publishedBy (string) - ID utilisateur du publieur
  • createdAt (timestamp ISO) - Quand le context a été créé pour la première fois

GET /api/v1/contexts

Liste tous les contexts du projet.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/contexts

Réponse :

json
{
  "data": [
    {
      "id": "ctx_...",
      "name": "Architecture Guide",
      "description": "Project architecture and coding standards",
      "activeVersion": { "version": 3, "publishedAt": "2024-01-15T10:00:00Z" },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

La réponse de liste omet le champ content complet pour des raisons de performance. Utilisez GET /api/v1/contexts/:id pour récupérer le contenu complet d’un context spécifique.

GET /api/v1/contexts/:id

Récupère un context par ID, y compris le contenu complet de la version active et un résumé des numéros de version disponibles.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/contexts/ctx_...

Réponse :

json
{
  "data": {
    "id": "ctx_...",
    "name": "Architecture Guide",
    "description": "Project architecture and coding standards",
    "activeVersion": {
      "version": 3,
      "content": "# Architecture\n\nThis project uses Next.js 16...",
      "publishedAt": "2024-01-15T10:00:00Z",
      "publishedBy": "user_..."
    },
    "versions": [1, 2, 3],
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

POST /api/v1/contexts

Crée un nouveau context. Créer un context ne publie pas de version initiale ; appelez PUT /api/v1/contexts/:id pour définir le contenu, ce qui crée automatiquement la version 1.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Architecture Guide",
    "description": "Project architecture and coding standards",
    "content": "# Architecture\n\nThis project uses..."
  }' \
  https://<deployment>.convex.site/api/v1/contexts

Champs du body :

  • name (string, requis) - Nom du context
  • description (string, optionnel) - Description courte
  • content (string, optionnel) - Contenu initial ; si fourni, publie automatiquement la version 1 et l’active

Réponse (201 Created) :

json
{ "data": { "id": "ctx_...", "name": "Architecture Guide" } }

PUT /api/v1/contexts/:id

Met à jour les métadonnées ou le contenu d’un context. Fournir une nouvelle valeur content crée une nouvelle version et l’active automatiquement. Mettre à jour uniquement name ou description ne crée pas de nouvelle version.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Architecture (Updated)\n\nThis project now uses..."
  }' \
  https://<deployment>.convex.site/api/v1/contexts/ctx_...

Champs du body (tous optionnels) :

  • name (string) - Nouveau nom du context
  • description (string) - Nouvelle description
  • content (string) - Nouveau contenu ; déclenche la création d’une nouvelle version

DELETE /api/v1/contexts/:id

Supprime un context (soft-delete). Le context est déplacé vers la corbeille et n’est plus servi aux agents. Les versions actives sont préservées ; le context peut être restauré depuis la corbeille.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/contexts/ctx_...

GET /api/v1/contexts/:id/versions

Liste toutes les versions publiées d’un context, du plus récent au plus ancien.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/contexts/ctx_.../versions

Réponse :

json
{
  "data": [
    {
      "version": 3,
      "content": "# Architecture (Updated)...",
      "isActive": true,
      "publishedAt": "2024-01-15T10:00:00Z",
      "publishedBy": "user_..."
    },
    {
      "version": 2,
      "content": "# Architecture...",
      "isActive": false,
      "publishedAt": "2024-01-10T08:00:00Z",
      "publishedBy": "user_..."
    }
  ]
}

PUT /api/v1/contexts/:id/versions/:v/activate

Active une version historique spécifique, en faisant la version servie aux agents. Utilisez ceci pour revenir à une version précédente sans republier. :v est le numéro de version entier.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/contexts/ctx_.../versions/2/activate

Réponse :

json
{ "data": { "activeVersion": 2, "activatedAt": "2024-01-16T09:00:00Z" } }

Informations

L’activation de version prend effet immédiatement. Tout run qui démarre après l’activation recevra la version nouvellement activée. Les runs en cours ne sont pas affectés car le contenu du context est capturé en snapshot au démarrage du run.

Skills

Les skills sont des bundles de fichiers versionnés qui étendent le comportement d’un agent. Chaque skill peut contenir plusieurs fichiers (templates de prompt, code de référence, configuration), tous publiés ensemble comme une seule version.

Objet Skill

json
{
  "id": "skill_...",
  "name": "React Component Generator",
  "description": "Generates accessible, typed React components with tests",
  "activeVersion": {
    "version": 2,
    "files": [
      {
        "name": "instructions.md",
        "content": "# React Component Generator\n\nWhen generating components..."
      },
      {
        "name": "example.tsx",
        "content": "// Example component structure..."
      }
    ],
    "publishedAt": "2024-01-12T14:00:00Z",
    "publishedBy": "user_..."
  },
  "createdAt": "2024-01-05T00:00:00Z"
}

GET /api/v1/skills

Liste tous les skills du projet.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/skills

GET /api/v1/skills/:id

Récupère un skill par ID, y compris tous les fichiers de la version active.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/skills/skill_...

POST /api/v1/skills

Crée un nouveau skill.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "React Component Generator",
    "description": "Generates accessible, typed React components with tests",
    "files": [
      {
        "name": "instructions.md",
        "content": "# React Component Generator\n\nWhen generating..."
      }
    ]
  }' \
  https://<deployment>.convex.site/api/v1/skills

Champs du body :

  • name (string, requis) - Nom du skill
  • description (string, optionnel) - Description affichée dans le dashboard
  • files (array, optionnel) - Objets de fichiers initiaux, chacun avec name et content ; si fourni, publie automatiquement la version 1

Réponse (201 Created) :

json
{ "data": { "id": "skill_...", "name": "React Component Generator" } }

PUT /api/v1/skills/:id

Met à jour les métadonnées du skill. Pour mettre à jour le contenu des fichiers, utilisez plutôt PUT /api/v1/skills/:id/publish, ce qui crée une nouvelle version immuable.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "React & React Native Component Generator" }' \
  https://<deployment>.convex.site/api/v1/skills/skill_...

DELETE /api/v1/skills/:id

Supprime un skill. Ceci retire le skill et toutes ses versions.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/skills/skill_...

PUT /api/v1/skills/:id/publish

Publie une nouvelle version d’un skill avec le contenu de fichier mis à jour. La nouvelle version devient active immédiatement.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "name": "instructions.md",
        "content": "# React Component Generator v2\n\nUpdated instructions..."
      },
      {
        "name": "example.tsx",
        "content": "// Updated example..."
      }
    ]
  }' \
  https://<deployment>.convex.site/api/v1/skills/skill_.../publish

Champs du body :

  • files (array, requis) - Nouvelle liste complète de fichiers ; ceci remplace tous les fichiers de la version précédente. Chaque item requiert name et content

Réponse :

json
{ "data": { "version": 3, "publishedAt": "2024-01-16T09:00:00Z" } }

GET /api/v1/skills/:id/versions

Liste toutes les versions publiées d’un skill.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/skills/skill_.../versions

Commands

Les commands sont des ensembles d’instructions en langage naturel mono-fichier que les agents peuvent invoquer par nom. Elles fonctionnent comme des macros réutilisables : définies une fois, référencées par nom dans les workflows.

Objet Command

json
{
  "id": "cmd_...",
  "name": "write-tests",
  "description": "Write comprehensive unit tests for new code",
  "activeVersion": {
    "version": 1,
    "content": "Write unit tests using Vitest for all exported functions and React components in the changed files. Aim for 80%+ branch coverage. Include edge cases for null/undefined inputs.",
    "publishedAt": "2024-01-10T12:00:00Z",
    "publishedBy": "user_..."
  },
  "createdAt": "2024-01-10T11:00:00Z"
}

Informations

Les noms de command doivent être des identifiants en minuscules avec des tirets (p. ex., write-tests, add-error-handling). Ils sont référencés dans les étapes de workflow comme /write-tests. Les noms doivent être uniques au sein d’un projet.

GET /api/v1/commands

Liste toutes les commands du projet.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/commands

GET /api/v1/commands/:id

Récupère une command par ID, y compris le contenu de la version active.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/commands/cmd_...

POST /api/v1/commands

Crée une nouvelle command.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "write-tests",
    "description": "Write comprehensive unit tests for new code",
    "content": "Write unit tests using Vitest for all exported functions..."
  }' \
  https://<deployment>.convex.site/api/v1/commands

Champs du body :

  • name (string, requis) - Nom de command en minuscules avec tirets ; doit être unique au sein du projet
  • description (string, optionnel) - Description lisible
  • content (string, optionnel) - Instructions de la command ; si fourni, publie automatiquement la version 1

Réponse (201 Created) :

json
{ "data": { "id": "cmd_...", "name": "write-tests" } }

PUT /api/v1/commands/:id

Met à jour les métadonnées de la command (nom ou description) sans créer de nouvelle version.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "description": "Write comprehensive unit and integration tests" }' \
  https://<deployment>.convex.site/api/v1/commands/cmd_...

DELETE /api/v1/commands/:id

Supprime une command et toutes ses versions.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/commands/cmd_...

PUT /api/v1/commands/:id/publish

Publie une nouvelle version d’une command avec le contenu mis à jour.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Write unit and integration tests using Vitest..."
  }' \
  https://<deployment>.convex.site/api/v1/commands/cmd_.../publish

Champs du body :

  • content (string, requis) - Nouveau texte d’instruction de la command

Réponse :

json
{ "data": { "version": 2, "publishedAt": "2024-01-16T09:00:00Z" } }

Scripts

Les scripts sont des fichiers exécutables versionnés qui s’exécutent dans la sandbox E2B durant l’exécution du workflow. Usages courants : migrations de base de données, pré-étapes de génération de code, passes de lint/format, et scripts de setup personnalisés.

Objet Script

json
{
  "id": "scr_...",
  "name": "setup-dev-env",
  "description": "Installs dependencies and sets up the development environment",
  "language": "bash",
  "activeVersion": {
    "version": 2,
    "content": "#!/bin/bash\nset -e\nnpm ci\nnpm run db:migrate\necho 'Setup complete'",
    "publishedAt": "2024-01-14T09:00:00Z",
    "publishedBy": "user_..."
  },
  "createdAt": "2024-01-01T00:00:00Z"
}
  • language (string) - Interpréteur du script : bash, python, ou node
  • activeVersion.content (string) - Le code source complet du script

Avertissement

Les scripts s’exécutent avec les mêmes permissions que l’utilisateur de la sandbox. Évitez de coder en dur des identifiants ou secrets dans le contenu du script - utilisez plutôt des variables d’environnement configurées dans les paramètres du projet.

GET /api/v1/scripts

Liste tous les scripts du projet.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/scripts

GET /api/v1/scripts/:id

Récupère un script par ID, y compris le contenu de la version active.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/scripts/scr_...

POST /api/v1/scripts

Crée un nouveau script.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "setup-dev-env",
    "description": "Installs dependencies and sets up the development environment",
    "language": "bash",
    "content": "#!/bin/bash\nset -e\nnpm ci\necho 'Done'"
  }' \
  https://<deployment>.convex.site/api/v1/scripts

Champs du body :

  • name (string, requis) - Nom de script en minuscules avec tirets ; doit être unique au sein du projet
  • language (string, requis) - Interpréteur : bash, python, ou node
  • description (string, optionnel) - Description lisible
  • content (string, optionnel) - Source du script ; si fourni, publie automatiquement la version 1

Réponse (201 Created) :

json
{ "data": { "id": "scr_...", "name": "setup-dev-env" } }

PUT /api/v1/scripts/:id

Met à jour les métadonnées du script sans créer de nouvelle version.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "description": "Full dev environment setup including DB migrations" }' \
  https://<deployment>.convex.site/api/v1/scripts/scr_...

DELETE /api/v1/scripts/:id

Supprime un script et toutes ses versions.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/scripts/scr_...

PUT /api/v1/scripts/:id/publish

Publie une nouvelle version d’un script avec le code source mis à jour.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "#!/bin/bash\nset -e\nnpm ci\nnpm run db:migrate\necho '"'"'Setup complete'"'"'"
  }' \
  https://<deployment>.convex.site/api/v1/scripts/scr_.../publish

Champs du body :

  • content (string, requis) - Nouveau code source du script

Réponse :

json
{ "data": { "version": 2, "publishedAt": "2024-01-16T09:00:00Z" } }

Résumé du cycle de vie des versions

Tous les types d’assets suivent le même cycle de vie de version :

  1. Créer - Créer l’enregistrement de l’asset (optionnellement avec un contenu initial pour auto-publier la v1)
  2. Brouillon - Utilisez PUT /:id pour mettre à jour les métadonnées ; les changements de contenu ici préparent une nouvelle version sans l’activer
  3. Publier - Utilisez PUT /:id/publish pour valider les changements préparés en une nouvelle version immuable et l’activer
  4. Revenir en arrière - Pour les contexts, utilisez PUT /:id/versions/:v/activate pour réactiver n’importe quelle version précédente

Informations

Les versions publiées sont immuables. Une fois qu’un numéro de version est assigné et qu’une version est publiée, son contenu ne peut pas être modifié. Pour changer le contenu, publiez toujours une nouvelle version.

Runs API

Démarrer des runs de workflow qui utilisent des contexts et skills

Webhooks & Callbacks

Opérations de callback internes pour les contexts et versions de contexts