# DS2API Admin API Endpoints: Complete Reference for Configuration and Management

> Explore the DS2API Admin API with over 30 REST endpoints for managing accounts, proxies, and configuration. Access detailed documentation for this comprehensive API reference.

- Repository: [CJACK./ds2api](https://github.com/CJackHwang/ds2api)
- Tags: api-reference
- Published: 2026-04-26

---

**The DS2API Admin API exposes 30+ REST endpoints under the `/admin` prefix, divided into public authentication routes and protected administrative routes for managing accounts, proxies, configuration keys, and chat history.**

The DS2API project by CJackHwang provides a proxy layer for DeepSeek AI API access. The Admin API, mounted under `/admin` via `router.Route("/admin", …)` in [`internal/server/router.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router.go), serves as the control plane for runtime configuration, credential rotation, and system health monitoring. All protected routes enforce access via the `adminauth.RequireAdmin` middleware, which validates admin JWT tokens or legacy admin keys.

## Authentication Endpoints

The authentication handlers in [`internal/httpapi/admin/auth/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/auth/routes.go) bootstrap administrative access and handle token lifecycle.

### Public Routes (No Authentication Required)

These endpoints require no Bearer token:

- **POST `/admin/login`** – Exchange an admin key or password for a time-bound JWT
- **GET `/admin/verify`** – Validate that a provided JWT is active and not expired

### Protected Auth Utilities

Once authenticated, additional configuration becomes available:

- **GET `/admin/vercel/config`** – Retrieve Vercel-specific authentication configuration

## Configuration Management Endpoints

The configuration management handlers in [`internal/httpapi/admin/configmgmt/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/configmgmt/routes.go) govern the runtime state of the DS2API server:

- **GET `/admin/config`** – Retrieve the full current runtime configuration as JSON
- **POST `/admin/config`** – Atomically replace the entire configuration object
- **POST `/admin/config/import`** – Import a specific configuration JSON payload
- **GET `/admin/config/export`** – Export configuration for backup or migration
- **GET `/admin/export`** – Alias for `/config/export` maintained for backward compatibility
- **POST `/admin/import`** – Bulk import accounts, keys, and related entities in a single transaction

### API Key Lifecycle

These endpoints manage consumer API keys (distinct from admin authentication):

- **POST `/admin/keys`** – Generate a new API key with metadata and rate limits
- **PUT `/admin/keys/{key}`** – Update an existing key's properties or description
- **DELETE `/admin/keys/{key}`** – Permanently revoke an API key

## Account Management Endpoints

Defined in [`internal/httpapi/admin/accounts/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/accounts/routes.go), these endpoints control the DeepSeek account pool:

- **GET `/admin/accounts`** – List all configured DeepSeek accounts with their health status
- **POST `/admin/accounts`** – Add a new DeepSeek account to the rotation pool
- **PUT `/admin/accounts/{identifier}`** – Update credentials or metadata for a specific account
- **DELETE `/admin/accounts/{identifier}`** – Remove an account from the pool

### Account Testing and Session Control

- **POST `/admin/accounts/test`** – Test a single account against a specific model and message payload
- **POST `/admin/accounts/test-all`** – Concurrently verify all configured accounts and return aggregated results
- **POST `/admin/accounts/sessions/delete-all`** – Invalidate every stored DeepSeek session token across the entire pool
- **GET `/admin/queue/status`** – Inspect the request-queue depth and latency for the account pool
- **POST `/admin/test`** – Run a quick health-check request against the DeepSeek API (general connectivity test)

## Proxy Management Endpoints

The proxy handlers in [`internal/httpapi/admin/proxies/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/proxies/routes.go) manage HTTP(S) proxy configurations for upstream requests:

- **GET `/admin/proxies`** – List all configured upstream proxies with their health status
- **POST `/admin/proxies`** – Create a new proxy configuration (URL, authentication, timeout settings)
- **PUT `/admin/proxies/{proxyID}`** – Modify an existing proxy's endpoint or credentials
- **DELETE `/admin/proxies/{proxyID}`** – Remove a proxy from the available pool

### Proxy Testing and Assignment

- **POST `/admin/proxies/test`** – Test connectivity and latency for a proxy configuration without persisting it
- **PUT `/admin/accounts/{identifier}/proxy`** – Bind a specific proxy to an individual DeepSeek account for granular routing

## Settings and Maintenance Endpoints

Located in [`internal/httpapi/admin/settings/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/settings/routes.go) and [`internal/httpapi/admin/history/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/history/routes.go):

### Administrative Settings

- **GET `/admin/settings`** – Read administrative settings including JWT expiry duration, password-hash status, and feature flags
- **PUT `/admin/settings`** – Update mutable server settings such as timeout values or logging levels
- **POST `/admin/settings/password`** – Rotate the admin password or regenerate its bcrypt hash

### Chat History Management

- **GET `/admin/chat-history`** – Retrieve paginated chat history entries with filtering options
- **GET `/admin/chat-history/{id}`** – Fetch a specific conversation transcript by its unique identifier
- **DELETE `/admin/chat-history/{id}`** – Purge a single history record permanently
- **DELETE `/admin/chat-history`** – Clear all stored chat history (destructive bulk operation)
- **PUT `/admin/chat-history/settings`** – Adjust retention policies and storage limits for conversation logs

## Development and Debug Endpoints

These routes in [`internal/httpapi/admin/rawsamples/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/rawsamples/routes.go) and [`internal/httpapi/admin/devcapture/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/devcapture/routes.go) assist with debugging and development workflows.

### Raw Sample Capture

- **POST `/admin/dev/raw-samples/capture`** – Capture a raw request/response pair from the DeepSeek API for inspection
- **GET `/admin/dev/raw-samples/query`** – Query previously captured samples with filtering criteria
- **POST `/admin/dev/raw-samples/save`** – Persist a captured sample into the repository for regression testing

### Development Captures

- **GET `/admin/dev/captures`** – List development-time captures such as token usage logs and request traces
- **DELETE `/admin/dev/captures`** – Clear all development capture logs to free storage

### Version Information

- **GET `/admin/version`** – Return the current DS2API version string and build information from [`internal/httpapi/admin/version/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/version/routes.go)

## How to Authenticate with the Admin API

All endpoints except `/admin/login` and `/admin/verify` require a valid JWT passed in the `Authorization: Bearer <token>` header. Obtain a token via the login endpoint:

```bash
curl -X POST https://your-host.com/admin/login \
     -H "Content-Type: application/json" \
     -d '{"key":"your-admin-key"}'

```

Example response:

```json
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

```

### Example: Listing DeepSeek Accounts

```bash
TOKEN=$(curl -s -X POST https://your-host.com/admin/login \
                -d '{"key":"admin"}' | jq -r .token)

curl -H "Authorization: Bearer $TOKEN" \
     https://your-host.com/admin/accounts

```

### Example: Adding a New API Key

```bash
curl -X POST https://your-host.com/admin/keys \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"key":"production-key-2024","description":"Production workload"}'

```

### Example: Updating Configuration

```bash
curl -X PUT https://your-host.com/admin/config \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jwt_expire_hours":48,"log_level":"debug"}'

```

### Example: Testing Proxy Connectivity

```bash
curl -X POST https://your-host.com/admin/proxies/test \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url":"http://proxy.example.com:8080","auth":"user:pass"}'

```

## Summary

- The DS2API Admin API root is mounted at `/admin` via `router.Route` in [`internal/server/router.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router.go)
- **Public routes** (`/login`, `/verify`) require no authentication and return JWTs for session management
- **Protected routes** enforce admin privileges through `adminauth.RequireAdmin` middleware validating Bearer tokens
- Configuration endpoints in [`internal/httpapi/admin/configmgmt/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/configmgmt/routes.go) handle atomic config swaps, API key rotation, and bulk import/export
- Account endpoints in [`internal/httpapi/admin/accounts/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/accounts/routes.go) support CRUD operations, bulk testing, and emergency session invalidation
- Proxy endpoints manage upstream HTTP(S) proxies and per-account proxy assignment via [`internal/httpapi/admin/proxies/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/proxies/routes.go)
- Chat history and development utilities provide observability and debugging capabilities for production deployments

## Frequently Asked Questions

### How do I obtain an authentication token for the DS2API Admin API?

Send a POST request to `/admin/login` with either the `DS2API_ADMIN_KEY` value or the admin password in the JSON body. The server responds with a JWT that must be included in the `Authorization: Bearer` header for all subsequent protected requests. Token expiration is configurable via the settings endpoints.

### What is the difference between `/config/export` and `/export` endpoints?

Both endpoints return the identical runtime configuration JSON payload. `/export` exists as a compatibility alias for `/config/export`, primarily maintained for legacy integrations. Use `/config/export` for new implementations as it follows the standardized resource-oriented URL pattern established in [`internal/httpapi/admin/configmgmt/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/configmgmt/routes.go).

### Can I assign different HTTP proxies to individual DeepSeek accounts?

Yes. While proxy configurations are defined globally via `/admin/proxies`, you can bind a specific proxy to a specific account using **PUT `/admin/accounts/{identifier}/proxy`**. This allows fine-grained routing where certain accounts use residential proxies while others use datacenter endpoints, all managed through the handlers in [`internal/httpapi/admin/proxies/routes.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/httpapi/admin/proxies/routes.go).

### How do I invalidate all active DeepSeek sessions immediately?

Send a POST request to `/admin/accounts/sessions/delete-all`. This endpoint triggers a mass invalidation of all stored session tokens across the account pool, forcing re-authentication on the next request. This is useful when rotating credentials or responding to potential security incidents.