# Qwen-Agent APIs: Complete Guide to the FastAPI Endpoint and Internal Methods

> Explore the Qwen-Agent APIs with this comprehensive guide covering the FastAPI endpoint and essential internal methods like change checkbox cache and pop url.

- Repository: [Qwen/Qwen-Agent](https://github.com/qwenlm/Qwen-Agent)
- Tags: api-reference
- Published: 2026-03-09

---

**Qwen-Agent exposes a single HTTP POST endpoint at `/endpoint` that handles three specific tasks—`change_checkbox`, `cache`, and `pop_url`—while additional capabilities are accessed through the Python SDK or Gradio UI.**

The Qwen-Agent framework from the [QwenLM/Qwen-Agent](https://github.com/QwenLM/Qwen-Agent) repository provides a lightweight server architecture for managing browsing history, caching web content, and handling popup URLs. Understanding the available Qwen-Agent APIs requires examining both the public REST interface and the internal Python methods that power the agent's functionality.

## Overview of Qwen-Agent API Architecture

### The Single HTTP Endpoint

Unlike comprehensive AI platforms that expose dozens of REST endpoints, Qwen-Agent adopts a minimalist approach with a single generic entry point. The API is implemented using **FastAPI** and defined in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py). This design consolidates all server-side operations through the `/endpoint` route, which dispatches requests based on a `task` field in the JSON payload.

The server runs as a subprocess launched by [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py), reading configuration from [`qwen_server/server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/server_config.json) (modeled by Pydantic schemas in [`qwen_server/schema.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/schema.py)). The specific port is controlled by the `fast_api_port` setting in this configuration file.

### Configuration and Server Startup

When the server initializes, it loads the global configuration to determine network parameters and workspace directories. The [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py) script orchestrates three separate processes: the database server (FastAPI), the workstation server, and the assistant server. Only the database server exposes the HTTP API endpoint.

## Available Qwen-Agent API Endpoints and Methods

### POST /endpoint: The Generic Task Handler

The `/endpoint` route accepts POST requests containing a JSON object with a mandatory `task` key. Based on the task value, the server executes one of three distinct operations:

**`change_checkbox`** – Toggles the checked state of a browsing record. This task invokes `change_checkbox_state()` (defined at lines 82-88 in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py)), which updates the `meta_data.jsonl` file to mark records as selected or deselected.

**`cache`** – Asynchronously caches web page content or local files into the workspace. This task spawns a separate process running `cache_page()` (lines 91-112), which stores the content and extracts a title using the **Memory** module. The function returns immediately with the status `'caching'` while the background process completes the storage operation.

**`pop_url`** – Adds a new URL or local file path to the popup list for UI display. This task calls `update_pop_url()` (lines 71-79), which appends the URL to `popup_url.jsonl` for retrieval by the frontend interface.

The handler implementation explicitly raises `NotImplementedError` for any unrecognized task values, ensuring strict validation of inputs.

## How to Call Qwen-Agent APIs: Code Examples

### Using cURL to Interact with the API

You can test the Qwen-Agent API directly from the command line using standard HTTP tools. Ensure the server is running (default port typically 8000 unless configured otherwise in [`server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/server_config.json)):

```bash

# Toggle the checkbox state for a specific record

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"change_checkbox","ckid":"ck-<record_id>"}'

# Asynchronously cache a web page

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"cache","url":"https://example.com","content":"<html>...</html>"}'

# Add a URL to the popup list

curl -X POST http://127.0.0.1:8000/endpoint \
     -H "Content-Type: application/json" \
     -d '{"task":"pop_url","url":"https://example.com/article.pdf"}'

```

### Python requests Implementation

For programmatic access, use the `requests` library to construct type-safe clients:

```python
import requests

BASE_URL = "http://127.0.0.1:8000/endpoint"

def call_qwen_agent_api(task, **kwargs):
    """Generic caller for the Qwen-Agent API."""
    payload = {"task": task, **kwargs}
    response = requests.post(BASE_URL, json=payload)
    response.raise_for_status()
    return response.json()

# Toggle checkbox state

result = call_qwen_agent_api("change_checkbox", ckid="ck-12345")
print(result)  # Output: {'result': 'changed'}

# Cache content asynchronously

result = call_qwen_agent_api(
    "cache", 
    url="https://example.com", 
    content="<p>Hello World</p>"
)
print(result)  # Output: 'caching'

# Update popup URL list

result = call_qwen_agent_api("pop_url", url="https://example.com/report.pdf")
print(result)  # Output: 'Update URL'

```

### Direct Python Function Calls (Internal API)

Developers integrating Qwen-Agent components directly can bypass the HTTP layer and invoke the underlying functions from `qwen_server.database_server`:

```python
from qwen_server.database_server import (
    change_checkbox_state, 
    cache_page, 
    update_pop_url
)

# Synchronously toggle checkbox (updates meta_data.jsonl)

change_checkbox_state("ck-12345")

# Synchronously cache page content (uses Memory module for title extraction)

cache_page(
    url="https://example.com", 
    content="<html><head><title>Example</title></head><body>...</body></html>"
)

# Update popup URL list (writes to popup_url.jsonl)

update_pop_url("https://example.com/report.pdf")

```

Note that `cache_page` runs synchronously when called directly, whereas the HTTP API spawns it as a background process via `multiprocessing.Process`.

## Key Files and Implementation Details

The Qwen-Agent API implementation spans several critical files in the repository:

| File | Role |
|------|------|
| [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py) | Implements the FastAPI application and the `/endpoint` route handler (`web_listening`), plus utility functions `change_checkbox_state()`, `cache_page()`, and `update_pop_url()`. |
| [`qwen_server/schema.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/schema.py) | Defines Pydantic models (`GlobalConfig`, `ServerConfig`, `PathConfig`) that validate [`server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/server_config.json) structure. |
| [`qwen_server/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/utils.py) | Provides helper functions for persisting browsing metadata and chat history to JSONL files. |
| [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py) | Orchestrates the three-server architecture (database, workstation, assistant) and launches the FastAPI subprocess. |
| [`qwen_server/server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/server_config.json) | Configuration file specifying `fast_api_port` and workspace directories. |

These files collectively define the public API surface of Qwen-Agent. The REST endpoint (`POST /endpoint`) represents the only network-exposed API; all other agent capabilities—including chat completions, writing assistance, and code interpretation—are accessed through the Python SDK (`qwen_agent` package) or the Gradio web interface.

## Summary

- **Qwen-Agent exposes a single HTTP API** via FastAPI at `POST /endpoint`, defined in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py).
- **Three task types** are supported: `change_checkbox` (toggle record selection), `cache` (asynchronously store web content), and `pop_url` (add URLs to the popup list).
- **Configuration** is managed through [`qwen_server/server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/server_config.json) and validated by Pydantic schemas in [`qwen_server/schema.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/schema.py).
- **Server startup** is handled by [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py), which launches the database server as a subprocess on the port specified by `fast_api_port`.
- **Alternative access** to the same functionality is available through direct Python imports from `qwen_server.database_server` for developers integrating the framework internally.

## Frequently Asked Questions

### Does Qwen-Agent provide a REST API for chat completions?

No, the Qwen-Agent framework does not expose chat completion functionality through a REST API. The only network-exposed endpoint is `POST /endpoint` in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py), which handles browsing record management and content caching. Chat, writing, and code interpreter capabilities are accessed through the Gradio web UI or the `qwen_agent` Python SDK.

### What is the default port for the Qwen-Agent API server?

The Qwen-Agent API server port is not hardcoded; it is read from the `fast_api_port` field in [`qwen_server/server_config.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/server_config.json). This configuration is validated by the `ServerConfig` Pydantic model in [`qwen_server/schema.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/schema.py) when [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py) launches the database server subprocess.

### Can I use Qwen-Agent functionality without the HTTP API?

Yes, developers can bypass the HTTP layer entirely by importing functions directly from `qwen_server.database_server`. The internal Python API exposes `change_checkbox_state()`, `cache_page()`, and `update_pop_url()`, which perform the same operations as the REST endpoint but run synchronously in the current process rather than through the FastAPI server.

### Where is the API endpoint handler implemented in the source code?

The `/endpoint` route handler is implemented as the `web_listening` async function in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/database_server.py) (lines 115-132). This function parses the incoming JSON payload, dispatches to the appropriate utility function based on the `task` field, and returns a `JSONResponse`. The FastAPI application setup and route registration occur in the same file, which is launched as a subprocess by [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py).