Cherry Studio API Agent Management Endpoints: Complete CRUD Reference

The Cherry Studio API server exposes seven REST endpoints at /v1/agents that provide full CRUD operations, pagination, and partial updates for autonomous agent management.

The cherryhq/cherry-studio repository implements a comprehensive agent management layer through its API server, enabling developers to programmatically create, configure, and orchestrate AI agents. All endpoints are defined in the agents handler module with Swagger documentation and follow RESTful conventions.

Overview of Agent Management Endpoints

The agent management API provides a complete lifecycle interface for autonomous agents. The implementation in src/main/apiServer/routes/agents/handlers/agents.ts handles HTTP requests and delegates business logic to the agentService and sessionService layers.

The seven exposed endpoints cover:

• Creation with automatic session provisioning
• Retrieval of single agents or paginated lists
• Full updates via PUT for complete configuration replacement
• Partial updates via PATCH for field-level modifications
• Deletion with cascading removal of sessions and logs

Endpoint Reference

Create Agent

POST /v1/agents

Creates a new agent and automatically provisions a default session. The handler implementation resides at lines 20-53 in handlers/agents.ts. Required fields include name, description, and model configuration.

List Agents

GET /v1/agents

Retrieves a paginated, sortable list of all agents. Supports query parameters for limit, offset, sortBy, and orderBy. Implemented at lines 84-118.

Get Agent by ID

GET /v1/agents/{agentId}

Fetches a single agent's complete configuration using its unique identifier. Returns 404 if the agent does not exist. Handler located at lines 122-154.

Update Agent (Full Replacement)

PUT /v1/agents/{agentId}

Replaces an existing agent's configuration entirely. Requires the complete agent payload; omitted fields are reset to defaults. Implementation spans lines 174-226.

Update Agent (Partial)

PATCH /v1/agents/{agentId}

Applies a partial update where only supplied fields are modified. Ideal for toggling settings or updating descriptions without affecting other configuration. Handler at lines 252-304.

Delete Agent

DELETE /v1/agents/{agentId}

Removes an agent permanently, including all associated sessions and logs. Cascading deletion is handled by the sessionService layer. Implemented at lines 322-364.

Code Examples

Creating a New Agent

const axios = require('axios');

const response = await axios.post('http://localhost:3000/v1/agents', {
  name: 'ResearchBot',
  description: 'Collects data from the web',
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 2000
});

console.log('Created agent:', response.data.id);

Listing Agents with Pagination

const { data } = await axios.get('http://localhost:3000/v1/agents', {
  params: { 
    limit: 10, 
    offset: 0, 
    sortBy: 'name', 
    orderBy: 'asc' 
  }
});

console.log(`Retrieved ${data.agents.length} of ${data.total} agents`);

Full Update via PUT

await axios.put('http://localhost:3000/v1/agents/abc123', {
  name: 'ResearchBot v2',
  description: 'Updated description with video analysis capability',
  model: 'gpt-4o',
  temperature: 0.5,
  maxTokens: 4000,
  // All fields required - omitted fields reset to defaults
});

Partial Update via PATCH

await axios.patch('http://localhost:3000/v1/agents/abc123', {
  description: 'Now includes video analysis and multilingual support',
  temperature: 0.3
  // Only these fields are modified; others remain unchanged
});

Deleting an Agent

await axios.delete('http://localhost:3000/v1/agents/abc123');
console.log('Agent and associated sessions removed');

Key Implementation Files

The agent management endpoints rely on a layered architecture with clear separation of concerns:

• src/main/apiServer/routes/agents/handlers/agents.ts – Contains all HTTP request handlers for the seven endpoints, including Swagger/OpenAPI annotations for automatic documentation generation.

• src/main/services/agents/agentService.ts – Business logic layer responsible for agent CRUD operations, validation, and orchestration with model providers.

• src/main/services/agents/sessionService.ts – Manages agent session lifecycle, including the automatic provisioning triggered during agent creation and cascading deletion during agent removal.

• src/main/apiServer/routes/agents/validators/agents.ts – Request validation schemas using Zod or Joi (depending on the framework) that enforce type safety and required fields before handlers execute.

Summary

• The Cherry Studio API exposes seven REST endpoints at /v1/agents providing complete agent lifecycle management.
• POST creates agents with automatic session provisioning, while DELETE performs cascading cleanup of sessions and logs.
• PUT requires complete payload replacement, whereas PATCH enables field-level partial updates.
• All handlers are implemented in src/main/apiServer/routes/agents/handlers/agents.ts with business logic delegated to agentService and sessionService.
• Request validation is enforced through dedicated validator schemas before handler execution.

Frequently Asked Questions

What is the difference between PUT and PATCH when updating an agent?

PUT performs a full replacement of the agent configuration, requiring every field in the request body and resetting omitted fields to their default values. PATCH applies a partial update where only the provided fields are modified, leaving all other existing configuration intact. Use PUT when you want to completely redefine an agent, and PATCH for minor adjustments like updating a description or changing a temperature setting.

Does deleting an agent remove all associated data?

Yes, the DELETE endpoint at /v1/agents/{agentId} performs a cascading deletion that removes the agent along with all its associated sessions and logs. This is handled by the sessionService layer to ensure data consistency and prevent orphaned session records. Once deleted, the agent and its history cannot be recovered through the API.

What parameters does the list agents endpoint support?

The GET /v1/agents endpoint supports pagination and sorting through query parameters: limit (number of results per page), offset (pagination offset), sortBy (field to sort by), and orderBy (sort direction, typically "asc" or "desc"). These parameters allow efficient browsing of large agent collections without retrieving all records at once.

Where is the request validation logic located?

Request validation is implemented in src/main/apiServer/routes/agents/validators/agents.ts using schema validation (likely Zod or similar). These schemas enforce type safety, required fields, and data constraints before the request reaches the handler functions in handlers/agents.ts. This separation ensures that business logic handlers only process validated, well-formed data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}