API Contexts & Assets

Riferimento completo per gli endpoint REST API dei context (documenti di conoscenza versionati), skill (comportamenti agente multi-file), command (comandi IA a file singolo) e script (automazione eseguibile) in CodeCourier.

14 min letto
apicontextsskills

Il sistema di asset di CodeCourier fornisce uno storage strutturato e versionato per la conoscenza e la configurazione di comportamento usate dagli agenti IA a runtime. Esistono quattro tipi di asset:

  • Context - Documenti di conoscenza di progetto riutilizzabili (guide di architettura, standard di codice, regole di business) iniettati nei prompt degli agenti. Ogni context mantiene una cronologia versioni completa; solo la versione attiva viene servita agli agenti.
  • Skill - Bundle multi-file che estendono le capacità di un agente. Le skill contengono frammenti di prompt, codice di esempio e istruzioni raggruppati in un pacchetto nominato e versionato.
  • Command - Insiemi di istruzioni in linguaggio naturale a file singolo che un agente può invocare per nome, simili a una macro riutilizzabile o uno slash command.
  • Script - Script shell o Python eseguibili che girano nell’ambiente sandbox. Gli script sono versionati e possono essere pubblicati indipendentemente dalla configurazione del workflow.

Tutti i tipi di asset seguono lo stesso modello di pubblicazione versionata: aggiorni un asset per preparare le modifiche, poi pubblichi per creare una nuova versione immutabile e attivarla. Le versioni precedenti restano accessibili e possono essere riattivate in qualsiasi momento.

Context

Oggetto 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) - Identificatore univoco del context, con prefisso ctx_
  • name (string) - Nome leggibile del context mostrato nella dashboard e iniettato come header nei prompt degli agenti
  • description (string) - Breve riepilogo di cosa contiene questo context; non viene iniettato nei prompt degli agenti
  • activeVersion (object | null) - La versione attualmente attiva servita agli agenti; null se non è mai stata pubblicata una versione
  • activeVersion.version (number) - Numero di versione monotonicamente crescente
  • activeVersion.content (string) - Il contenuto Markdown o testo semplice completo di questa versione
  • activeVersion.publishedAt (timestamp ISO) - Quando questa versione è stata pubblicata
  • activeVersion.publishedBy (string) - ID utente del pubblicatore
  • createdAt (timestamp ISO) - Quando il context è stato creato per la prima volta

GET /api/v1/contexts

Elenca tutti i context del progetto.

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

Risposta:

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 risposta della lista omette il campo contentcompleto per motivi di performance. Usa GET /api/v1/contexts/:id per recuperare il contenuto completo di uno specifico context.

GET /api/v1/contexts/:id

Ottieni un context per ID, incluso il contenuto completo della versione attiva e un riepilogo dei numeri di versione disponibili.

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

Risposta:

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

Crea un nuovo context. Creare un context non pubblica una versione iniziale; chiama PUT /api/v1/contexts/:id per impostare il contenuto, il che crea automaticamente la versione 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

Campi del body:

  • name (string, obbligatorio) - Nome del context
  • description (string, opzionale) - Breve descrizione
  • content (string, opzionale) - Contenuto iniziale; se fornito, pubblica automaticamente la versione 1 e la imposta come attiva

Risposta (201 Created):

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

PUT /api/v1/contexts/:id

Aggiorna i metadati o il contenuto di un context. Fornire un nuovo valore content crea una nuova versione e la attiva automaticamente. Aggiornare solo name o description non crea una nuova versione.

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

Campi del body (tutti opzionali):

  • name (string) - Nuovo nome del context
  • description (string) - Nuova descrizione
  • content (string) - Nuovo contenuto; attiva la creazione di una nuova versione

DELETE /api/v1/contexts/:id

Elimina (soft-delete) un context. Il context viene spostato nel cestino e non viene più servito agli agenti. Le versioni attive vengono preservate; il context può essere ripristinato dal cestino.

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

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

Elenca tutte le versioni pubblicate di un context, dalla più recente.

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

Risposta:

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

Attiva una specifica versione storica, rendendola la versione servita agli agenti. Usa questo per tornare a una versione precedente senza ripubblicare. :v è il numero di versione intero.

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

Risposta:

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

Informazioni

L’attivazione della versione ha effetto immediato. Qualsiasi run che parte dopo l’attivazione riceverà la versione appena attivata. I run in corso non vengono influenzati poiché il contenuto del context viene catturato come snapshot all’avvio del run.

Skill

Le skill sono bundle di file versionati che estendono il comportamento di un agente. Ogni skill può contenere più file (template di prompt, codice di riferimento, configurazione), tutti pubblicati insieme come singola versione.

Oggetto 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

Elenca tutte le skill del progetto.

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

GET /api/v1/skills/:id

Ottieni una skill per ID, inclusi tutti i file nella versione attiva.

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

POST /api/v1/skills

Crea una nuova 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

Campi del body:

  • name (string, obbligatorio) - Nome della skill
  • description (string, opzionale) - Descrizione mostrata nella dashboard
  • files (array, opzionale) - Oggetti file iniziali, ciascuno con name e content; se forniti, pubblica automaticamente la versione 1

Risposta (201 Created):

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

PUT /api/v1/skills/:id

Aggiorna i metadati della skill. Per aggiornare il contenuto dei file, usa invece PUT /api/v1/skills/:id/publish, che crea una nuova versione immutabile.

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

Elimina una skill. Questo rimuove la skill e tutte le sue versioni.

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

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

Pubblica una nuova versione di una skill con il contenuto dei file aggiornato. La nuova versione diventa attiva immediatamente.

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

Campi del body:

  • files (array, obbligatorio) - Nuova lista completa di file; sostituisce tutti i file della versione precedente. Ogni elemento richiede name e content

Risposta:

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

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

Elenca tutte le versioni pubblicate di una skill.

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

Command

I command sono insiemi di istruzioni in linguaggio naturale a file singolo che gli agenti possono invocare per nome. Funzionano come macro riutilizzabili: definiti una volta, referenziati per nome nei workflow.

Oggetto 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"
}

Informazioni

I nomi dei command devono essere identificatori in minuscolo con trattini (ad es., write-tests, add-error-handling). Vengono referenziati negli step del workflow come /write-tests. I nomi devono essere univoci all’interno di un progetto.

GET /api/v1/commands

Elenca tutti i command del progetto.

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

GET /api/v1/commands/:id

Ottieni un command per ID, incluso il contenuto della versione attiva.

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

POST /api/v1/commands

Crea un nuovo 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

Campi del body:

  • name (string, obbligatorio) - Nome del command in minuscolo con trattini; deve essere univoco all’interno del progetto
  • description (string, opzionale) - Descrizione leggibile
  • content (string, opzionale) - Istruzioni del command; se fornito, pubblica automaticamente la versione 1

Risposta (201 Created):

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

PUT /api/v1/commands/:id

Aggiorna i metadati del command (nome o descrizione) senza creare una nuova versione.

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

Elimina un command e tutte le sue versioni.

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

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

Pubblica una nuova versione di un command con il contenuto aggiornato.

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

Campi del body:

  • content (string, obbligatorio) - Nuovo testo di istruzione del command

Risposta:

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

Script

Gli script sono file eseguibili versionati che girano dentro la sandbox E2B durante l’esecuzione del workflow. Usi comuni: migrazioni database, pre-step di generazione codice, passate di lint/format e script di setup personalizzati.

Oggetto 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) - Interprete dello script: bash, python, o node
  • activeVersion.content (string) - Il codice sorgente completo dello script

Avvertimento

Gli script vengono eseguiti con gli stessi permessi dell’utente sandbox. Evita di scrivere credenziali o segreti direttamente nel contenuto dello script - usa invece variabili d’ambiente configurate nelle impostazioni del progetto.

GET /api/v1/scripts

Elenca tutti gli script del progetto.

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

GET /api/v1/scripts/:id

Ottieni uno script per ID, incluso il contenuto della versione attiva.

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

POST /api/v1/scripts

Crea un nuovo 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

Campi del body:

  • name (string, obbligatorio) - Nome dello script in minuscolo con trattini; deve essere univoco all’interno del progetto
  • language (string, obbligatorio) - Interprete: bash, python, o node
  • description (string, opzionale) - Descrizione leggibile
  • content (string, opzionale) - Sorgente dello script; se fornito, pubblica automaticamente la versione 1

Risposta (201 Created):

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

PUT /api/v1/scripts/:id

Aggiorna i metadati dello script senza creare una nuova versione.

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

Elimina uno script e tutte le sue versioni.

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

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

Pubblica una nuova versione di uno script con il codice sorgente aggiornato.

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

Campi del body:

  • content (string, obbligatorio) - Nuovo codice sorgente dello script

Risposta:

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

Riepilogo del ciclo di vita delle versioni

Tutti i tipi di asset seguono lo stesso ciclo di vita di versione:

  1. Crea - Crea il record dell’asset (opzionalmente con contenuto iniziale per auto-pubblicare la v1)
  2. Bozza - Usa PUT /:id per aggiornare i metadati; le modifiche al contenuto qui preparano una nuova versione senza attivarla
  3. Pubblica - Usa PUT /:id/publish per confermare le modifiche preparate come nuova versione immutabile e attivarla
  4. Rollback - Per i context, usa PUT /:id/versions/:v/activate per riattivare qualsiasi versione precedente

Informazioni

Le versioni pubblicate sono immutabili. Una volta che un numero di versione viene assegnato e una versione viene pubblicata, il suo contenuto non può essere modificato. Per cambiare il contenuto, pubblica sempre una nuova versione.

Runs API

Avvia run di workflow che usano context e skill

Webhooks & Callbacks

Operazioni di callback interne per context e versioni di context