API Server

The core role of the API server:Expose the AI capabilities configured in Cherry Studio through a local interface to the outside world(also the underlying dependency for agent features), for other programs to call.

Use case: You have already configured providers such as OpenAI, Anthropic, DeepSeek in Cherry Studio. If your other tools (for example, a coding plugin or custom script) want to call the same AI capabilities,API serverit will expose a standard interface on the local machine, allowing these tools to directly reuse Cherry Studio's existing configuration without having to register separate accounts with each provider.

When do you need to enable it?

• Use agents → Must be enabled
• To connect an Agent to an IM platform (channel) → Must be enabled
• Only use Cherry Studio's standard chat, drawing, translation, and similar features → No need to enable

Recommended reading first Concepts introduction Learn about Agent, channels, and related concepts.

Enable the API server

1. Open Settings → API Server
2. The default listening port is 23333, you can enter 1000-65535 any free port between
3. Click the green button in the upper-right corner ▶ Start button

When not enabled, it shows "Stopped" and prompts "Please enable the API server to use agent features"

After successful startup, the status turns green running, and the listening address is displayed http://127.0.0.1:<port>:

Running state, includes "Restart" and "Stop" buttons

How to change the port: The port input box is read-only while the server is running. To modify it, first click ⏹ Stop, then restart after changing the port.

API key and authorization header

API keyIn the form of cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, automatically generated when the API server is enabled for the first time andretained persistently, restarting the server will not refresh it.

If you need to regenerate it manually:You must first click ⏹ to stop the server, then the Regenerate button will appear on the right side of the key (while running, only the copy button is shown). After clicking, the old key becomes invalid immediately, and starting again will generate a new key.

When calling the API, add the following to the request headers:

Authorization: Bearer cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The API key has permission to access all providers in your Cherry Studio,do not expose it on the public internet or in team-sharing channels.

View API documentation

Click the API documentation button in the upper-right corner of the page to open the built-in OpenAPI interface documentation (Swagger style), including complete endpoints and request examples.

Port conflict troubleshooting

Startup fails with the prompt EADDRINUSE: address already in use 127.0.0.1:<port> when:

1. most likely another Cherry Studio instance is using the same port
2. Click ⏹ Stop, change the port to another free value, then start again
3. or run in the terminal lsof -i :<port>(macOS / Linux) find the process using it and handle it

Restart and Stop

• Restart: Click the ↻ icon, commonly used to force refresh all connections after regenerating the key
• Stop: Click the red ⏹ icon to immediately shut down the service; connections currently in use agents and channel will be interrupted as well

The API server only listens on 127.0.0.1,will notExpose to the local network or the public internet. If cross-machine access is needed, use an SSH reverse tunnel or a similar solution.

Next step

• After enabling, you can continue configuring agents
• If you want to connect the Agent to IM platforms such as Feishu / Telegram / Discord, please read channel

---

💡 Get help and submit feedback

If you encounter any questions, bugs, or have suggestions for feature improvements during configuration or use, please refer to Feedback and Suggestions the official channels provided there.