> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/advanced-basic/api-server.md). # 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 server**it 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](/docs/en-us/cherry-studio/preview/agent.md) → **Must be enabled** * To connect an Agent to an IM platform ([channel](/docs/en-us/advanced-basic/agent-channels.md)) → **Must be enabled** * Only use Cherry Studio's standard chat, drawing, translation, and similar features → **No need to enable** > Recommended reading first [Concepts introduction](/docs/en-us/advanced-basic/concepts-101.md) 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:`:

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

{% hint style="info" %} **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. {% endhint %} ### API key and authorization header **API key**In the form of `cs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, automatically generated when the API server is enabled for the first time and**retained 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 ``` {% hint style="warning" %} 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**. {% endhint %} ### 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:` 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 :`(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](/docs/en-us/cherry-studio/preview/agent.md) and [channel](/docs/en-us/advanced-basic/agent-channels.md) will be interrupted as well {% hint style="info" %} The API server only listens on `127.0.0.1`,**will not**Expose to the local network or the public internet. If cross-machine access is needed, use an SSH reverse tunnel or a similar solution. {% endhint %} ### Next step * After enabling, you can continue configuring [agents](/docs/en-us/cherry-studio/preview/agent.md) * If you want to connect the Agent to IM platforms such as Feishu / Telegram / Discord, please read [channel](/docs/en-us/advanced-basic/agent-channels.md) *** ### 💡 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](/docs/en-us/question-contact/suggestions.md) the official channels provided there. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cherryai.com.cn/docs/en-us/advanced-basic/api-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.