DS2API Admin API Endpoints: Complete Reference for Configuration and Management

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, 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 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 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, 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 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 and 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 and 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

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:

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

Example response:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Example: Listing DeepSeek Accounts

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

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

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

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
• 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 handle atomic config swaps, API key rotation, and bulk import/export
• Account endpoints in 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
• 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.

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}