# Cherry Studio API Agent Management Endpoints: Complete CRUD Reference

> Explore Cherry Studio API agent management endpoints for full CRUD operations. Discover REST endpoints at /v1/agents for seamless autonomous agent management with pagination and updates.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: api-reference
- Published: 2026-02-27

---

**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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/handlers/agents.ts). This separation ensures that business logic handlers only process validated, well-formed data.