Agents & Sessions

Two workspace inventories that sit alongside Projects:

• Agents (Skills) — reusable, named personas for the chat tool. The product now calls them Skills; every route is served under both /api/v1/skills (current name) and /api/v1/agents (original path, kept working) with identical behavior. An agent's description is the system instruction the model adopts.
• Sessions — the containers every generation lands in. One endpoint enumerates them across all 17 generation and chat types.

Endpoint

GET    /api/v1/skills            (alias: /api/v1/agents)
POST   /api/v1/skills            (alias: /api/v1/agents)
PUT    /api/v1/skills/:id        (alias: /api/v1/agents/:id)
DELETE /api/v1/skills/:id        (alias: /api/v1/agents/:id)

GET    /api/v1/sessions
PATCH  /api/v1/sessions/:sessionId
DELETE /api/v1/sessions/:sessionId
POST   /api/v1/sessions/:sessionId/restore
PATCH  /api/v1/sessions/:sessionId/project
POST   /api/v1/sessions/move
GET    /api/v1/sessions/:sessionId/generations
POST   /api/v1/sessions/:sessionId/generations/move
POST   /api/v1/sessions/:sessionId/split
POST   /api/v1/sessions/organize/undo/:operationId

The examples below use /api/v1/agents; /api/v1/skills behaves identically.

Listing Agents

GET /api/v1/agents

Returns your personal agents, the global preset agents, and agents a member has explicitly shared to your active organization. Deleted agents are excluded. Rows are sorted newest-created first across all three groups.

curl "https://api.kolbo.ai/api/v1/agents?search=director" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "agents": [
    {
      "id": "66a1c8a2e4b0a3c1d9f5e001",
      "name": "Creative Director",
      "description": "You are a senior creative director. Turn any brief into a structured shot list…",
      "emoji": "<emoji>",
      "thumbnail": null,
      "is_global": false,
      "file_ids": [],
      "created_at": "2026-07-12T16:38:55.871Z",
      "updated_at": "2026-07-12T16:38:55.871Z"
    }
  ],
  "count": 1,
  "pagination": { "page": 1, "limit": 50, "total": 1, "has_more": false }
}

emoji holds a single emoji character; description, emoji and thumbnail come back as null when unset.

Creating an Agent

POST /api/v1/agents

* At least one of name / description must be a non-empty string, otherwise 400.

Any other body field (for example an organization-sharing flag) is dropped by the API route, so an agent created here is always a personal agent.

curl -X POST https://api.kolbo.ai/api/v1/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creative Director",
    "description": "You are a senior creative director. Turn any brief into a structured shot list with camera, lens, and lighting notes."
  }'

The response is { "success": true, "agent": { … } } in the shape shown above. Retrieval indexing for any attached files is queued in the background, so a freshly created agent is usable immediately but its file knowledge lands a moment later.

Updating an Agent

PUT /api/v1/agents/:id

At least one of those six fields must be present, otherwise 400. Only your own personal agents can be updated: a missing id, a global preset, and an agent owned by someone else all return 404. Fields outside that list are dropped, so is_global, ownership, and organization scope cannot be reassigned through this route. If the agent is changed elsewhere (for example in the app) between the server's read and write, the update returns 409 (The skill changed. Reload it before saving your edits.) — re-send it.

The response is { "success": true, "agent": { … } }. Retrieval indexing is re-queued in the background after every successful update.

Deleting an Agent

DELETE /api/v1/agents/:id

Owner only. A missing id, a global preset, or someone else's agent returns 404.

{ "success": true, "deleted": true, "id": "66a1c8a2e4b0a3c1d9f5e001" }

Listing Sessions

GET /api/v1/sessions

Enumerates sessions across all generation and chat types, newest activity first. Trashed (soft-deleted) sessions are excluded.

curl "https://api.kolbo.ai/api/v1/sessions?project_id=65f1c8a2e4b0a3c1d9f5e123&type=image&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "sessions": [
    {
      "session_id": "65f1c8a2e4b0a3c1d9f5e999",
      "name": "API Image Generation - 2026-07-12",
      "type": "image",
      "types": ["image"],
      "project_id": "65f1c8a2e4b0a3c1d9f5e123",
      "created_at": "2026-07-12T16:38:55.871Z",
      "updated_at": "2026-07-12T18:02:11.004Z",
      "owner": { "userId": "65f1c8a2e4b0a3c1d9f5e001", "name": "Dana", "avatar": null },
      "is_mine": true
    }
  ],
  "pagination": { "page": 1, "limit": 50, "returned": 1, "has_more": false }
}

Session types

The same 16 keys are valid for the type / types filters here and for the type hint on the rename, delete, restore, and move endpoints:

image, video, video_from_image, music, speech, image_edit, sound, creative_director, chat, elements, first_last_frame, lipsync, video_from_video, transcription, global_image_edit, global_video_edit

3D generations are project-scoped and have no session, so they never appear in this list.

A session's name comes back as null when it was never named, and project_id as null in the rare case a session is not attached to a project.

Renaming, Trashing, and Restoring a Session

PATCH  /api/v1/sessions/:sessionId           body: { name, type? }
DELETE /api/v1/sessions/:sessionId           query: type?
POST   /api/v1/sessions/:sessionId/restore   body: { type? }

• Rename needs edit permission on the session's project (the session owner always qualifies); otherwise 403.
• Delete is a soft delete: the session is moved to the trash (deletedAt is set) and disappears from GET /sessions. Its generations and media are not touched. Needs delete permission (owner always qualifies).
• Restore brings a trashed session back. It needs the same delete permission, and only finds sessions that are currently trashed.

An invalid id returns 400; a session that does not exist, is not attached to a project, or sits in a project you cannot access returns 404.

curl -X PATCH https://api.kolbo.ai/api/v1/sessions/65f1c8a2e4b0a3c1d9f5e999 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Scene 03 — rooftop chase" }'

Each route returns { "success": true, "session": { session_id, name, type, types, project_id } }; delete adds deleted: true and deleted_at, and restore adds restored: true. All three sit on the 120-requests-per-minute media-library limiter.

Moving a Session

PATCH /api/v1/sessions/:sessionId/project relocates a session with all of its generations and media to another project. To move many at once use POST /api/v1/sessions/move, and to reorganize generations between sessions use the generations / split routes. Full reference: Projects → Moving a Session Between Projects, Moving Many Sessions at Once, Reorganizing Work Between Sessions and Undoing a Reorganization.

The move, split, generation-move, and undo routes share a stricter 20 requests per minute limiter; listing a session's generations uses the 120/min media-library limiter.

MCP Tools

The matching @kolbo/mcp tools are list_skills, create_skill, update_skill, delete_skill (also registered under their original names list_agents, create_agent, update_agent, delete_agent, which take agent_id where the new ones take skill_id), plus list_sessions, rename_session, delete_session, restore_session, move_session, bulk_move_sessions, list_session_generations, move_generations_to_session, split_session, and undo_session_organization.

1. list_skills { search: "director" }   -> resolve a name to a skill id
2. list_sessions { project_id }         -> find work that landed in the wrong place
3. move_session  { session_id, project_id }
4. delete_session { session_id }        -> trash the empty leftover, if any

Related