Contexts & Assets API

Complete reference for contexts (versioned knowledge documents), skills (multi-file agent behaviors), commands (single-file AI commands), and scripts (executable automation) REST API endpoints in CodeCourier.

14 min read
apicontextsskills

CodeCourier's asset system provides structured, versioned storage for the knowledge and behavior configuration used by AI agents at runtime. There are four asset types:

  • Contexts -- Reusable project-knowledge documents (architecture guides, coding standards, business rules) injected into agent prompts. Each context maintains a full version history; only the active version is served to agents.
  • Skills-- Multi-file bundles that extend an agent's capabilities. Skills contain prompt fragments, example code, and instructions grouped into a named, versioned package.
  • Commands -- Single-file natural-language instructions that an agent can invoke by name, similar to a reusable macro or slash command.
  • Scripts -- Executable shell or Python scripts that run in the sandbox environment. Scripts are versioned and can be published independently of the workflow configuration.

All asset types follow the same versioned publish model: you update an asset to stage changes, then publish to create a new immutable version and activate it. Previous versions remain accessible and can be reactivated at any time.

Contexts

Context Object

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) -- Unique context identifier, prefixed with ctx_
  • name (string) -- Human-readable context name shown in the dashboard and injected as a header in agent prompts
  • description (string) -- Brief summary of what this context contains; not injected into agent prompts
  • activeVersion (object | null) -- The currently active version served to agents; null if no version has ever been published
  • activeVersion.version (number) -- Monotonically increasing version number
  • activeVersion.content (string) -- The full Markdown or plain-text content of this version
  • activeVersion.publishedAt (ISO timestamp) -- When this version was published
  • activeVersion.publishedBy (string) -- User ID of the publisher
  • createdAt (ISO timestamp) -- When the context was first created

GET /api/v1/contexts

List all contexts for the project.

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

Response:

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

The list response omits the full content field for performance. Use GET /api/v1/contexts/:id to retrieve the complete content of a specific context.

GET /api/v1/contexts/:id

Get a context by ID, including the full content of the active version and a summary of available version numbers.

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

Response:

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

Create a new context. Creating a context does not publish an initial version; call PUT /api/v1/contexts/:id to set content, which creates version 1 automatically.

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 fields:

  • name (string, required) -- Context name
  • description (string, optional) -- Short description
  • content (string, optional) -- Initial content; if provided, automatically publishes version 1 and sets it as active

Response (201 Created):

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

PUT /api/v1/contexts/:id

Update context metadata or content. Providing a new content value creates a new version and automatically activates it. Updating only name or description does not create a new 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_...

Body fields (all optional):

  • name (string) -- New context name
  • description (string) -- New description
  • content (string) -- New content; triggers creation of a new version

DELETE /api/v1/contexts/:id

Soft-delete a context. The context moves to trash and is no longer served to agents. Active versions are preserved; the context can be restored from trash.

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

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

List all published versions for a context, newest first.

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

Response:

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

Activate a specific historical version, making it the version served to agents. Use this to roll back to a previous version without republishing. :v is the integer version number.

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

Response:

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

Info

Version activation takes effect immediately. Any run that starts after activation will receive the newly activated version. In-flight runs are not affected since context content is snapshot at run start.

Skills

Skills are versioned bundles of files that extend an agent's behavior. Each skill can contain multiple files (prompt templates, reference code, configuration), all published together as a single version.

Skill Object

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

List all skills for the project.

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

GET /api/v1/skills/:id

Get a skill by ID, including all files in the active version.

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

POST /api/v1/skills

Create a new 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

Body fields:

  • name (string, required) -- Skill name
  • description (string, optional) -- Description shown in the dashboard
  • files (array, optional) -- Initial file objects, each with name and content; if provided, publishes version 1 automatically

Response (201 Created):

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

PUT /api/v1/skills/:id

Update skill metadata. To update the file contents, use PUT /api/v1/skills/:id/publish instead, which creates a new immutable version.

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

Delete a skill. This removes the skill and all its versions.

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

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

Publish a new version of a skill with updated file content. The new version becomes active immediately.

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 fields:

  • files (array, required) -- Complete new file list; this replaces all files in the previous version. Each item requires name and content

Response:

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

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

List all published versions for a skill.

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

Commands

Commands are single-file, natural-language instruction sets that agents can invoke by name. They work like reusable macros: define once, reference by name in workflows.

Command Object

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 names must be lowercase, hyphenated identifiers (e.g., write-tests, add-error-handling). They are referenced in workflow steps as /write-tests. Names must be unique within a project.

GET /api/v1/commands

List all commands for the project.

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

GET /api/v1/commands/:id

Get a command by ID, including the active version content.

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

POST /api/v1/commands

Create a new 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

Body fields:

  • name (string, required) -- Lowercase hyphenated command name; must be unique within the project
  • description (string, optional) -- Human-readable description
  • content (string, optional) -- Command instructions; if provided, publishes version 1 automatically

Response (201 Created):

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

PUT /api/v1/commands/:id

Update command metadata (name or description) without creating a new 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

Delete a command and all its versions.

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

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

Publish a new version of a command with updated content.

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 fields:

  • content (string, required) -- New command instruction text

Response:

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

Scripts

Scripts are versioned executable files that run inside the E2B sandbox during workflow execution. Common uses: database migrations, code generation pre-steps, lint/format passes, and custom setup scripts.

Script Object

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) -- Script interpreter: bash, python, or node
  • activeVersion.content (string) -- The full script source code

Warning

Scripts execute with the same permissions as the sandbox user. Avoid hard-coding credentials or secrets in script content -- use environment variables configured in project settings instead.

GET /api/v1/scripts

List all scripts for the project.

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

GET /api/v1/scripts/:id

Get a script by ID, including the active version content.

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

POST /api/v1/scripts

Create a new 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

Body fields:

  • name (string, required) -- Lowercase hyphenated script name; must be unique within the project
  • language (string, required) -- Interpreter: bash, python, or node
  • description (string, optional) -- Human-readable description
  • content (string, optional) -- Script source; if provided, publishes version 1 automatically

Response (201 Created):

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

PUT /api/v1/scripts/:id

Update script metadata without creating a new 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

Delete a script and all its versions.

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

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

Publish a new version of a script with updated source code.

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 fields:

  • content (string, required) -- New script source code

Response:

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

Version Lifecycle Summary

All asset types follow the same version lifecycle:

  1. Create -- Create the asset record (optionally with initial content to auto-publish v1)
  2. Draft -- Use PUT /:id to update metadata; content changes here stage a new version without activating it
  3. Publish -- Use PUT /:id/publish to commit the staged changes as a new immutable version and activate it
  4. Rollback -- For contexts, use PUT /:id/versions/:v/activate to reactivate any previous version

Info

Published versions are immutable. Once a version number is assigned and a version is published, its content cannot be changed. To change content, always publish a new version.

Runs API

Start workflow runs that use contexts and skills

Webhooks & Callbacks

Internal callback operations for contexts and context versions