Contexts & Assets API

Vollständige Referenz für die REST-API-Endpunkte von Kontexten (versionierte Wissensdokumente), Skills (Agent-Verhalten mit mehreren Dateien), Commands (KI-Befehle in einer einzigen Datei) und Skripten (ausführbare Automatisierungen) in CodeCourier.

14 Min. Lesezeit
apicontextsskills

Das Asset-System von CodeCourier bietet strukturierte, versionierte Speicherung des Wissens und der Verhaltenskonfiguration, die KI-Agenten zur Laufzeit verwenden. Es gibt vier Asset-Typen:

  • Kontexte -- Wiederverwendbare Projektwissens-Dokumente (Architektur-Leitfäden, Coding-Standards, Geschäftsregeln), die in Agent-Prompts eingefügt werden. Jeder Kontext führt einen vollständigen Versionsverlauf; nur die aktive Version wird an Agenten ausgeliefert.
  • Skills -- Bundles aus mehreren Dateien, die die Fähigkeiten eines Agenten erweitern. Skills enthalten Prompt-Fragmente, Beispielcode und Anweisungen, gebündelt zu einem benannten, versionierten Paket.
  • Commands -- Natürlichsprachliche Anweisungen in einer einzigen Datei, die ein Agent über den Namen aufrufen kann, ähnlich einem wiederverwendbaren Makro oder Slash-Command.
  • Skripte -- Ausführbare Shell- oder Python-Skripte, die in der Sandbox-Umgebung laufen. Skripte sind versioniert und können unabhängig von der Workflow-Konfiguration veröffentlicht werden.

Alle Asset-Typen folgen demselben versionierten Publish-Modell: Sie aktualisieren ein Asset, um Änderungen zu staffieren, und veröffentlichen es dann, um eine neue, unveränderliche Version zu erstellen und sie zu aktivieren. Vorherige Versionen bleiben zugänglich und können jederzeit reaktiviert werden.

Kontexte

Kontext-Objekt

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) -- Eindeutiger Kontext-Bezeichner mit dem Präfix ctx_
  • name (string) -- Menschenlesbarer Kontextname, der im Dashboard angezeigt und als Header in Agent-Prompts eingefügt wird
  • description (string) -- Kurze Zusammenfassung des Kontextinhalts; wird nicht in Agent-Prompts eingefügt
  • activeVersion (object | null) -- Die aktuell aktive Version, die an Agenten ausgeliefert wird; null, wenn noch keine Version veröffentlicht wurde
  • activeVersion.version (number) -- Monoton ansteigende Versionsnummer
  • activeVersion.content (string) -- Der vollständige Markdown- oder Klartext-Inhalt dieser Version
  • activeVersion.publishedAt (ISO-Zeitstempel) -- Wann diese Version veröffentlicht wurde
  • activeVersion.publishedBy (string) -- User-ID des Veröffentlichenden
  • createdAt (ISO-Zeitstempel) -- Wann der Kontext erstmals erstellt wurde

GET /api/v1/contexts

Alle Kontexte des Projekts auflisten.

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

Antwort:

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

Die Listen-Antwort lässt das vollständige Feld content aus Performance-Gründen weg. Verwenden Sie GET /api/v1/contexts/:id, um den vollständigen Inhalt eines bestimmten Kontextes abzurufen.

GET /api/v1/contexts/:id

Einen Kontext per ID abrufen, einschließlich des vollständigen Inhalts der aktiven Version und einer Zusammenfassung der verfügbaren Versionsnummern.

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

Antwort:

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

Einen neuen Kontext erstellen. Das Erstellen eines Kontextes veröffentlicht keine initiale Version; rufen Sie PUT /api/v1/contexts/:id auf, um Inhalt zu setzen - dies erzeugt automatisch 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

Body-Felder:

  • name (string, erforderlich) -- Kontextname
  • description (string, optional) -- Kurzbeschreibung
  • content (string, optional) -- Initialer Inhalt; falls angegeben, wird automatisch Version 1 veröffentlicht und als aktiv gesetzt

Antwort (201 Created):

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

PUT /api/v1/contexts/:id

Kontext-Metadaten oder -Inhalt aktualisieren. Das Übergeben eines neuen content-Werts erzeugt eine neue Version und aktiviert sie automatisch. Werden nur name oder description aktualisiert, wird keine neue Version erstellt.

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

Body-Felder (alle optional):

  • name (string) -- Neuer Kontextname
  • description (string) -- Neue Beschreibung
  • content (string) -- Neuer Inhalt; löst die Erstellung einer neuen Version aus

DELETE /api/v1/contexts/:id

Einen Kontext per Soft-Delete löschen. Der Kontext wandert in den Papierkorb und wird nicht mehr an Agenten ausgeliefert. Aktive Versionen bleiben erhalten; der Kontext kann aus dem Papierkorb wiederhergestellt werden.

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

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

Alle veröffentlichten Versionen eines Kontextes auflisten, neueste zuerst.

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

Antwort:

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

Eine bestimmte historische Version aktivieren, sodass sie die an Agenten ausgelieferte Version wird. Verwenden Sie dies, um ohne Republish auf eine vorherige Version zurückzuwechseln. :v ist die ganzzahlige Versionsnummer.

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

Antwort:

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

Info

Die Aktivierung einer Version wird sofort wirksam. Jeder Run, der nach der Aktivierung startet, erhält die neu aktivierte Version. Laufende Runs sind nicht betroffen, da der Kontextinhalt zu Run-Beginn als Snapshot festgehalten wird.

Skills

Skills sind versionierte Bundles aus Dateien, die das Verhalten eines Agenten erweitern. Jedes Skill kann mehrere Dateien enthalten (Prompt-Templates, Referenzcode, Konfiguration), die gemeinsam als eine einzige Version veröffentlicht werden.

Skill-Objekt

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

Alle Skills des Projekts auflisten.

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

GET /api/v1/skills/:id

Ein Skill per ID abrufen, einschließlich aller Dateien der aktiven Version.

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

POST /api/v1/skills

Ein neues Skill erstellen.

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

Body-Felder:

  • name (string, erforderlich) -- Skill-Name
  • description (string, optional) -- Im Dashboard angezeigte Beschreibung
  • files (array, optional) -- Initiale Datei-Objekte, jedes mit name und content; falls angegeben, wird automatisch Version 1 veröffentlicht

Antwort (201 Created):

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

PUT /api/v1/skills/:id

Skill-Metadaten aktualisieren. Um die Datei-Inhalte zu aktualisieren, verwenden Sie stattdessen PUT /api/v1/skills/:id/publish, das eine neue unveränderliche Version erzeugt.

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

Ein Skill löschen. Damit werden das Skill und alle seine Versionen entfernt.

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

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

Eine neue Version eines Skills mit aktualisiertem Datei-Inhalt veröffentlichen. Die neue Version wird sofort aktiv.

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

Body-Felder:

  • files (array, erforderlich) -- Vollständige neue Dateiliste; ersetzt alle Dateien der vorherigen Version. Jedes Element benötigt name und content

Antwort:

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

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

Alle veröffentlichten Versionen eines Skills auflisten.

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

Commands

Commands sind natürlichsprachliche Anweisungssätze in einer einzigen Datei, die Agenten über den Namen aufrufen können. Sie funktionieren wie wiederverwendbare Makros: einmal definieren, in Workflows per Namen referenzieren.

Command-Objekt

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

Info

Command-Namen müssen Bezeichner in Kleinbuchstaben mit Bindestrichen sein (z. B. write-tests, add-error-handling). Sie werden in Workflow-Schritten als /write-tests referenziert. Namen müssen innerhalb eines Projekts eindeutig sein.

GET /api/v1/commands

Alle Commands des Projekts auflisten.

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

GET /api/v1/commands/:id

Ein Command per ID abrufen, einschließlich des Inhalts der aktiven Version.

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

POST /api/v1/commands

Ein neues Command erstellen.

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

Body-Felder:

  • name (string, erforderlich) -- Command-Name in Kleinbuchstaben mit Bindestrichen; muss im Projekt eindeutig sein
  • description (string, optional) -- Menschenlesbare Beschreibung
  • content (string, optional) -- Command-Anweisungen; falls angegeben, wird automatisch Version 1 veröffentlicht

Antwort (201 Created):

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

PUT /api/v1/commands/:id

Command-Metadaten (Name oder Beschreibung) aktualisieren, ohne eine neue Version zu erzeugen.

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

Ein Command und alle seine Versionen löschen.

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

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

Eine neue Version eines Commands mit aktualisiertem Inhalt veröffentlichen.

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

Body-Felder:

  • content (string, erforderlich) -- Neuer Command-Anweisungstext

Antwort:

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

Skripte

Skripte sind versionierte, ausführbare Dateien, die innerhalb der E2B-Sandbox während der Workflow-Ausführung laufen. Häufige Einsätze: Datenbankmigrationen, Pre-Steps zur Codegenerierung, Lint-/Format-Läufe und individuelle Setup-Skripte.

Skript-Objekt

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) -- Skript-Interpreter: bash, python oder node
  • activeVersion.content (string) -- Der vollständige Skript-Quellcode

Warnung

Skripte werden mit denselben Berechtigungen wie der Sandbox-Benutzer ausgeführt. Vermeiden Sie es, Zugangsdaten oder Secrets im Skript-Inhalt hart zu kodieren -- verwenden Sie stattdessen die in den Projekteinstellungen konfigurierten Umgebungsvariablen.

GET /api/v1/scripts

Alle Skripte des Projekts auflisten.

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

GET /api/v1/scripts/:id

Ein Skript per ID abrufen, einschließlich des Inhalts der aktiven Version.

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

POST /api/v1/scripts

Ein neues Skript erstellen.

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

Body-Felder:

  • name (string, erforderlich) -- Skriptname in Kleinbuchstaben mit Bindestrichen; muss im Projekt eindeutig sein
  • language (string, erforderlich) -- Interpreter: bash, python oder node
  • description (string, optional) -- Menschenlesbare Beschreibung
  • content (string, optional) -- Skript-Quellcode; falls angegeben, wird automatisch Version 1 veröffentlicht

Antwort (201 Created):

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

PUT /api/v1/scripts/:id

Skript-Metadaten aktualisieren, ohne eine neue Version zu erzeugen.

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

Ein Skript und alle seine Versionen löschen.

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

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

Eine neue Version eines Skripts mit aktualisiertem Quellcode veröffentlichen.

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

Body-Felder:

  • content (string, erforderlich) -- Neuer Skript-Quellcode

Antwort:

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

Zusammenfassung des Versions-Lifecycles

Alle Asset-Typen folgen demselben Versions-Lifecycle:

  1. Erstellen -- Den Asset-Datensatz erstellen (optional mit initialem Inhalt, um v1 automatisch zu veröffentlichen)
  2. Entwurf -- Verwenden Sie PUT /:id, um Metadaten zu aktualisieren; Inhaltsänderungen hier staffieren eine neue Version, ohne sie zu aktivieren
  3. Veröffentlichen -- Verwenden Sie PUT /:id/publish, um die gestaffelten Änderungen als neue unveränderliche Version zu committen und zu aktivieren
  4. Rollback -- Für Kontexte: Verwenden Sie PUT /:id/versions/:v/activate, um jede vorherige Version zu reaktivieren

Info

Veröffentlichte Versionen sind unveränderlich. Sobald eine Versionsnummer vergeben und eine Version veröffentlicht ist, kann ihr Inhalt nicht mehr geändert werden. Veröffentlichen Sie zur Inhaltsänderung immer eine neue Version.

Runs API

Workflow-Runs starten, die Kontexte und Skills nutzen

Webhooks & Callbacks

Interne Callback-Operationen für Kontexte und Kontextversionen