ThinkWatch API 参考#

本文档提供 ThinkWatch 所有 HTTP 端点的完整参考。平台运行两个服务器：

---

认证方案#

网关接受 API 密钥或 JWT。控制台管理端点需要 JWT，除非另有说明。管理员端点还额外要求 admin 角色。

---

Gateway 端点（端口 3000）#

网关在单一端口上提供三种 API 格式，客户端可以使用任意偏好的格式：

三个端点使用相同的认证方式（API Key 或 JWT），经过相同的模型路由器和速率限制器，并生成相同的用量记录和审计日志。

限流与预算#

请求发往上游之前，按此前的用量检查其 API 密钥与密钥所属用户的限流和预算；token 在响应之后计入，由响应缓存应答的请求同样计入。所属用户的限额来自其角色（全局分配的角色，以及用户所在团队挂载的角色），按最严格的合并，再应用用户自己的覆盖。超出限额的请求返回 429，Retry-After 给出限额释放前的秒数，错误消息注明是哪一项限额，例如 Rate limited: user:requests/1m。被这些限额拒绝的请求，以及密钥无权使用所请求模型的请求，不计入任何限额。

**路由上限。**模型路由可以设置「RPM 上限」和「TPM 上限」（在路由编辑器中设置），都按一分钟的滑动窗口计数，TPM 上限与其他 token 限额一样按加权 token 计。达到任一上限的路由会被跳过，由该模型的下一条路由处理请求；剩余路由全部达到上限时，请求返回 429 和 Retry-After，标签为 route:requests/1m 或 route:tokens/1m。这样的请求已经通过调用方自己的限额，并计入其中。

**无法检查限额时。**Redis 无法访问，或加载请求的限额时数据库出错，由 security.rate_limit_fail_closed 决定：关闭（默认）时请求照常进行，不受这些限额约束，并记录一条警告；打开时拒绝请求，返回 429 和 Retry-After: 30，标签为 rate_limiter_unavailable、budget_unavailable 或 limits_unavailable。路由上限同样遵循这一设置。见无法检查限额时。

GET /v1/usage 告诉客户端它的密钥已用多少、限额还剩多少。

POST /v1/chat/completions#

OpenAI 兼容的聊天补全端点。将请求代理到已配置的上游提供商。

认证： API Key 或 JWT

请求体#

{
  "model": "string",
  "messages": [
    {
      "role": "system" | "user" | "assistant",
      "content": "string"
    }
  ],
  "temperature": 0.7,
  "top_p": 1.0,
  "max_tokens": 4096,
  "stream": false,
  "stop": ["string"],
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0
}

响应体（非流式）#

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711929600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

响应体（流式，stream: true）#

响应为 text/event-stream SSE 事件流：

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711929600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711929600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: [DONE]

示例#

# Non-streaming
curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Streaming
curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

错误响应#

---

GET /v1/models#

列出通过网关可用的模型。使用 API 密钥调用时，只列出该密钥可以使用的模型。

认证： API Key 或 JWT

请求#

无请求体。无查询参数。

响应体#

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1711929600,
      "owned_by": "openai"
    },
    {
      "id": "claude-sonnet-4-20250514",
      "object": "model",
      "created": 1711929600,
      "owned_by": "anthropic"
    }
  ]
}

示例#

curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer tw-your-api-key"

错误响应#

---

GET /v1/usage#

查询调用方 API 密钥在 AI 网关上已用多少、限额还剩多少。客户端可以据此向用户显示剩余额度，或在限额拒绝请求之前放慢速度。

认证： 可访问 AI 网关的 API Key，与模型请求相同

调用它不计入任何限额，不写请求日志，也不算作一次使用密钥：last_used_at 保持不变，因此轮询不会让闲置的密钥免于不活跃超时。

请求#

无请求体。无查询参数。

响应体#

{
  "scope": "key",
  "usage": {
    "requests_today": 12,
    "tokens_today": 48210,
    "requests_month": 340,
    "tokens_month": 1290455,
    "cost_usd_month": 3.82
  },
  "limits": [
    {
      "scope": "key",
      "kind": "tokens",
      "window": "daily",
      "window_secs": null,
      "limit": 100000,
      "used": 48210,
      "resets_at": "2026-10-12T00:00:00Z"
    },
    {
      "scope": "key",
      "kind": "requests",
      "window": "1m",
      "window_secs": 60,
      "limit": 60,
      "used": 4,
      "resets_at": null
    }
  ],
  "expires_at": "2026-12-31T00:00:00Z"
}

回答针对两种对象之一，由 scope 指明：

• "key"：密钥在 AI 网关上设有自己的限额。limits 只列出密钥自己的限额，used 按这把密钥计数；usage 是密钥自己的用量，跨轮换累计。
• "user"：密钥没有自己的限额。limits 列出其所属用户的有效限额（各角色的限额，包括团队授予的角色，按最严格的合并，再应用用户自己的覆盖），used 按该用户的全部用量计数；usage 是该用户所有密钥的合计。用户也没有限额时，limits 为空。

因此，持有一把没有自己限额的密钥，就能看到其所属用户的合计用量与限额；交给他人使用的密钥应设置自己的限额。

剩余比例最小的限额排在最前。MCP 网关上的限额不列出。usage 从升级到 ThinkWatch 3.5.0 时开始计数。

示例#

curl http://localhost:3000/v1/usage \
  -H "Authorization: Bearer tw-your-api-key"

错误响应#

---

POST /v1/messages#

Anthropic Messages API 端点。接受原生 Anthropic 格式的请求并代理到已配置的上游提供商。这允许 Claude Code 和 Anthropic SDK 直接连接，无需在客户端进行格式转换。

认证： API Key 或 JWT

请求体#

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, Claude"
    }
  ],
  "stream": false,
  "system": "You are a helpful assistant.",
  "temperature": 0.7
}

响应体（非流式）#

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 10
  }
}

响应体（流式，stream: true）#

响应为遵循 Anthropic 流式格式的 text/event-stream SSE 事件流：

event: message_start
data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: message_stop
data: {"type":"message_stop"}

示例#

curl -X POST http://localhost:3000/v1/messages \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

错误响应#

---

POST /v1/responses#

OpenAI Responses API 端点（2025 格式）。接受 OpenAI Responses 格式的请求，支持简单字符串输入和结构化消息数组。

认证： API Key 或 JWT

请求体#

{
  "model": "gpt-4o",
  "input": "What is the capital of France?",
  "instructions": "You are a helpful geography assistant.",
  "stream": false,
  "temperature": 0.7,
  "max_output_tokens": 4096
}

input 字段可以是简单字符串或消息对象数组：

{
  "model": "gpt-4o",
  "input": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
    {"role": "user", "content": "What is 2+2?"}
  ]
}

响应体（非流式）#

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1711929600,
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 8,
    "total_tokens": 23
  }
}

示例#

curl -X POST http://localhost:3000/v1/responses \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "What is the capital of France?"
  }'

错误响应#

---

POST /mcp#

MCP（Model Context Protocol）Streamable HTTP 传输端点。接受 JSON-RPC 2.0 请求并路由到已注册的 MCP 服务器。

认证： API Key 或 JWT

请求体#

标准 JSON-RPC 2.0 封装：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {}
  }
}

常用方法：

响应头#

响应体#

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool output here"
      }
    ]
  }
}

示例#

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
  }'

# Call a tool (include session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: session-uuid-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {"name": "search_docs", "arguments": {"query": "setup guide"}}
  }'

错误响应#

---

DELETE /mcp#

关闭 MCP 会话并释放相关资源。

认证： API Key 或 JWT

请求头#

响应#

HTTP/1.1 204 No Content

示例#

curl -X DELETE http://localhost:3000/mcp \
  -H "Authorization: Bearer tw-your-api-key" \
  -H "Mcp-Session-Id: session-uuid-here"

错误响应#

---

GET /health#

基本网关健康检查。

认证： 公开

响应体#

{
  "status": "ok"
}

示例#

curl http://localhost:3000/health

---

GET /health/live#

存活探针。如果服务器进程正在运行，返回 200。

认证： 公开

响应体#

{
  "status": "alive"
}

示例#

curl http://localhost:3000/health/live

---

GET /health/ready#

就绪探针。如果所有关键依赖（PostgreSQL、Redis）可达，返回 200。如果任何关键依赖不可用，返回 503。

认证： 公开

响应体（健康）#

{
  "status": "ready"
}

响应体（不健康）#

{
  "status": "not_ready",
  "reason": "redis unreachable"
}

示例#

curl http://localhost:3000/health/ready

---

GET /metrics#

Prometheus 兼容的指标端点。暴露请求延迟直方图、Token 吞吐量计数器、活跃连接数仪表和错误率计数器。

认证： 公开（无需认证）

端口： 3000（网关）

响应#

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="POST",endpoint="/v1/chat/completions",status="200"} 1520

# HELP http_request_duration_seconds HTTP request latency
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{endpoint="/v1/chat/completions",le="0.5"} 300
...

示例#

curl http://localhost:3000/metrics

注意： 此端点用于 Prometheus 抓取。在生产环境中请通过网络策略限制访问。

---

Console 端点（端口 3001）#

初始化设置#

GET /api/setup/status#

检查系统是否已初始化（即是否已创建管理员用户）。

认证： 公开

响应体#

{
  "initialized": false,
  "needs_setup": true
}

示例#

curl http://localhost:3001/api/setup/status

---

POST /api/setup/initialize#

执行系统初始化设置：创建首个管理员用户并可选配置首个 AI 提供商。此端点仅在系统尚未初始化时可用。

认证： 公开（仅在未初始化时）

请求体#

{
  "admin": {
    "email": "admin@example.com",
    "display_name": "Admin",
    "password": "your-secure-password"
  },
  "provider": {
    "name": "openai-prod",
    "display_name": "OpenAI Production",
    "provider_type": "openai",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
  }
}

响应体#

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "uuid",
    "email": "admin@example.com",
    "display_name": "Admin",
    "role": "admin"
  }
}

示例#

curl -X POST http://localhost:3001/api/setup/initialize \
  -H "Content-Type: application/json" \
  -d '{
    "admin": {
      "email": "admin@example.com",
      "display_name": "Admin",
      "password": "your-secure-password"
    }
  }'

错误响应#

安全： 此端点限制为每分钟 5 次请求，并对数据库执行二次检查以防止竞态条件。

---

认证#

POST /api/auth/login#

使用邮箱和密码进行认证以获取 JWT 令牌。

认证： 公开

请求体#

{
  "email": "string",
  "password": "string"
}

响应体#

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "display_name": "Jane Doe",
    "role": "user"
  }
}

示例#

curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "secret"}'

错误响应#

---

POST /api/auth/register#

创建新用户账户。

认证： 公开

请求体#

{
  "email": "string",
  "display_name": "string",
  "password": "string"
}

响应体#

{
  "id": "uuid",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "role": "user",
  "created_at": "2026-01-15T10:30:00Z"
}

示例#

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "display_name": "New User",
    "password": "strongpassword123"
  }'

错误响应#

---

POST /api/auth/refresh#

使用刷新令牌换取新的访问令牌/刷新令牌对。

认证： 公开（需要有效的刷新令牌）

请求体#

{
  "refresh_token": "string"
}

响应体#

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900
}

示例#

curl -X POST http://localhost:3001/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOi..."}'

错误响应#

---

GET /api/auth/sso/authorize#

启动 OIDC 授权码流程。将用户浏览器重定向到已配置的身份提供商。

认证： 公开

查询参数#

无。服务器生成随机的 state 和 nonce，将它们存储在 Redis 中，并构建 OIDC 授权 URL。

响应#

HTTP/1.1 302 Found
Location: https://idp.example.com/authorize?client_id=...&redirect_uri=...&state=...&nonce=...&scope=openid+email+profile&response_type=code

示例#

# Typically opened in a browser, not curl
curl -v http://localhost:3001/api/auth/sso/authorize

---

GET /api/auth/sso/callback#

OIDC 回调端点。身份提供商在用户认证后重定向到此处。

认证： 公开

查询参数#

响应体#

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "uuid",
    "email": "sso-user@corp.com",
    "display_name": "SSO User",
    "role": "user"
  }
}

错误响应#

---

GET /api/auth/me#

返回当前已认证用户的个人资料。

认证： JWT

响应体#

{
  "id": "uuid",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "role": "user",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-03-20T14:00:00Z"
}

示例#

curl http://localhost:3001/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

API 密钥#

API 密钥自己的限流与预算在控制台中密钥编辑对话框的「限额」标签页里编辑：按请求数或加权 token 计的限流（窗口为 1m、5m、1h、5h、1d 或 1w），以及按日、周或月计的加权 token 预算，各自显示已用量。它们叠加在所属用户的限额之上，单独计数，并在密钥轮换后保留。该标签页通过 /api/admin/limits/api_key/{id}/rules、/api/admin/limits/api_key/{id}/budgets 和 /api/admin/limits/api_key/{id}/usage 读取和修改限额。读取需要 rate_limits:read，修改需要 rate_limits:write，且权限范围须覆盖这把密钥；没有修改权限时标签页只读，没有读取权限时对话框中不显示「限额」标签页。

GET /api/keys#

列出当前认证用户的所有 API 密钥。

认证： JWT

响应体#

[
  {
    "id": "uuid",
    "name": "Production Key",
    "prefix": "tw-prod",
    "allowed_models": ["gpt-4o", "claude-sonnet-4-20250514"],
    "rate_limit_rpm": 60,
    "expires_at": "2026-06-01T00:00:00Z",
    "created_at": "2026-01-15T10:30:00Z",
    "last_used_at": "2026-03-28T09:15:00Z"
  }
]

注意： 创建后不会再返回完整密钥值。仅显示 prefix 用于标识。

示例#

curl http://localhost:3001/api/keys \
  -H "Authorization: Bearer eyJhbGciOi..."

---

POST /api/keys#

创建新的 API 密钥。

认证： JWT

请求体#

{
  "name": "string",
  "allowed_models": ["string"],
  "rate_limit_rpm": 60,
  "expires_in_days": 90
}

响应体#

{
  "id": "uuid",
  "name": "Production Key",
  "key": "tw-sk-a1b2c3d4e5f6...",
  "allowed_models": ["gpt-4o"],
  "rate_limit_rpm": 60,
  "expires_at": "2026-06-01T00:00:00Z",
  "created_at": "2026-03-28T10:00:00Z"
}

重要： key 字段仅在创建时返回一次。请妥善保存。

示例#

curl -X POST http://localhost:3001/api/keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "allowed_models": ["gpt-4o"],
    "rate_limit_rpm": 120,
    "expires_in_days": 30
  }'

错误响应#

---

GET /api/keys/{id}#

获取特定 API 密钥的详情。

认证： JWT

路径参数#

响应体#

{
  "id": "uuid",
  "name": "Production Key",
  "prefix": "tw-prod",
  "allowed_models": ["gpt-4o"],
  "rate_limit_rpm": 60,
  "expires_at": "2026-06-01T00:00:00Z",
  "created_at": "2026-01-15T10:30:00Z",
  "last_used_at": "2026-03-28T09:15:00Z"
}

错误响应#

---

DELETE /api/keys/{id}#

撤销 API 密钥。此操作不可逆。

认证： JWT

路径参数#

响应#

HTTP/1.1 204 No Content

示例#

curl -X DELETE http://localhost:3001/api/keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

PATCH /api/keys/{id}#

更新现有 API 密钥的设置。

认证： JWT

路径参数#

请求体#

{
  "allowed_models": ["gpt-4o", "claude-sonnet-4-20250514"],
  "rate_limit_rpm": 120,
  "expires_in_days": 60,
  "rotation_interval_days": 90,
  "inactivity_timeout_days": 30
}

响应体#

{
  "id": "uuid",
  "name": "Production Key",
  "prefix": "tw-prod",
  "allowed_models": ["gpt-4o", "claude-sonnet-4-20250514"],
  "rate_limit_rpm": 120,
  "expires_at": "2026-08-01T00:00:00Z",
  "rotation_interval_days": 90,
  "inactivity_timeout_days": 30,
  "updated_at": "2026-04-01T10:00:00Z"
}

示例#

curl -X PATCH http://localhost:3001/api/keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit_rpm": 120,
    "inactivity_timeout_days": 30
  }'

错误响应#

---

POST /api/keys/{id}/rotate#

轮换 API 密钥。生成新的密钥值并返回。旧密钥进入宽限期（可配置），在此期间新旧密钥均被接受。

认证： JWT

路径参数#

响应体#

{
  "id": "uuid",
  "name": "Production Key",
  "key": "tw-sk-newkey123456...",
  "grace_period_ends_at": "2026-04-02T10:00:00Z",
  "rotated_at": "2026-04-01T10:00:00Z"
}

重要： 新的 key 值仅返回一次。旧密钥在 grace_period_ends_at 之前保持有效。

示例#

curl -X POST http://localhost:3001/api/keys/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

GET /api/keys/expiring#

列出指定天数内即将过期的 API 密钥。

认证： JWT

查询参数#

响应体#

[
  {
    "id": "uuid",
    "name": "Production Key",
    "prefix": "tw-prod",
    "expires_at": "2026-04-07T00:00:00Z",
    "days_remaining": 5,
    "owner_email": "user@example.com"
  }
]

示例#

curl "http://localhost:3001/api/keys/expiring?days=14" \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

管理员 — 提供商#

GET /api/admin/providers#

列出所有已配置的 AI 提供商。

认证： JWT（管理员）

响应体#

[
  {
    "id": "uuid",
    "name": "openai-prod",
    "display_name": "OpenAI Production",
    "provider_type": "openai",
    "base_url": "https://api.openai.com/v1",
    "is_active": true,
    "created_at": "2026-01-10T08:00:00Z"
  }
]

注意： 响应中不会返回提供商的 api_key。

示例#

curl http://localhost:3001/api/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..."

---

POST /api/admin/providers#

注册新的上游 AI 提供商。

认证： JWT（管理员）

请求体#

{
  "name": "string",
  "display_name": "string",
  "provider_type": "string",
  "base_url": "string",
  "api_key": "string"
}

响应体#

{
  "id": "uuid",
  "name": "openai-prod",
  "display_name": "OpenAI Production",
  "provider_type": "openai",
  "base_url": "https://api.openai.com/v1",
  "is_active": true,
  "created_at": "2026-03-28T10:00:00Z"
}

示例#

curl -X POST http://localhost:3001/api/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "anthropic-prod",
    "display_name": "Anthropic Production",
    "provider_type": "anthropic",
    "base_url": "https://api.anthropic.com",
    "api_key": "sk-ant-..."
  }'

错误响应#

---

GET /api/admin/providers/{id}#

获取特定提供商的详情。

认证： JWT（管理员）

路径参数#

响应体#

与列表响应中的单个项目 Schema 相同。

错误响应#

---

DELETE /api/admin/providers/{id}#

删除提供商。引用其模型的现有密钥将无法再解析。

认证： JWT（管理员）

响应#

HTTP/1.1 204 No Content

示例#

curl -X DELETE http://localhost:3001/api/admin/providers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

管理员 — 用户#

GET /api/admin/users#

列出系统中的所有用户。

认证： JWT（管理员）

响应体#

[
  {
    "id": "uuid",
    "email": "admin@example.com",
    "display_name": "Admin User",
    "role": "admin",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-03-15T12:00:00Z"
  }
]

示例#

curl http://localhost:3001/api/admin/users \
  -H "Authorization: Bearer eyJhbGciOi..."

---

POST /api/admin/users#

创建新用户（管理员配置）。

认证： JWT（管理员）

请求体#

{
  "email": "string",
  "display_name": "string",
  "password": "string",
  "role": "string"
}

响应体#

{
  "id": "uuid",
  "email": "newadmin@example.com",
  "display_name": "New Admin",
  "role": "admin",
  "created_at": "2026-03-28T10:00:00Z"
}

示例#

curl -X POST http://localhost:3001/api/admin/users \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@example.com",
    "display_name": "Ops User",
    "password": "securepassword",
    "role": "operator"
  }'

错误响应#

---

管理员 — MCP 服务器#

GET /api/mcp/servers#

列出所有已注册的 MCP 服务器。

认证： JWT（管理员）

响应体#

[
  {
    "id": "uuid",
    "name": "docs-search",
    "description": "Internal documentation search",
    "endpoint_url": "https://mcp.internal.corp/docs",
    "transport_type": "streamable_http",
    "auth_type": "bearer",
    "is_active": true,
    "tool_count": 3,
    "created_at": "2026-02-01T08:00:00Z"
  }
]

示例#

curl http://localhost:3001/api/mcp/servers \
  -H "Authorization: Bearer eyJhbGciOi..."

---

POST /api/mcp/servers#

注册新的 MCP 服务器。

认证： JWT（管理员）

请求体#

{
  "name": "string",
  "description": "string",
  "endpoint_url": "string",
  "transport_type": "string",
  "auth_type": "string",
  "auth_secret": "string"
}

响应体#

{
  "id": "uuid",
  "name": "docs-search",
  "description": "Internal documentation search",
  "endpoint_url": "https://mcp.internal.corp/docs",
  "transport_type": "streamable_http",
  "auth_type": "bearer",
  "is_active": true,
  "created_at": "2026-03-28T10:00:00Z"
}

示例#

curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "jira-tools",
    "description": "Jira issue management tools",
    "endpoint_url": "https://mcp.internal.corp/jira",
    "auth_type": "bearer",
    "auth_secret": "mcp-server-token-here"
  }'

错误响应#

---

GET /api/mcp/servers/{id}#

获取特定 MCP 服务器的详情。

认证： JWT（管理员）

路径参数#

响应体#

与列表响应中的单个项目 Schema 相同。

---

DELETE /api/mcp/servers/{id}#

移除 MCP 服务器注册。活跃的会话将被终止。

认证： JWT（管理员）

响应#

HTTP/1.1 204 No Content

示例#

curl -X DELETE http://localhost:3001/api/mcp/servers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOi..."

---

POST /api/mcp/servers/{id}/discover#

触发 MCP 服务器的工具发现。连接到服务器，调用 tools/list，并将发现的工具存储到数据库中。

认证： JWT（管理员）

路径参数#

响应体#

{
  "server_id": "uuid",
  "tools_discovered": 5,
  "tools": [
    {
      "name": "search_issues",
      "description": "Search Jira issues by JQL",
      "input_schema": {
        "type": "object",
        "properties": {
          "jql": {"type": "string"}
        },
        "required": ["jql"]
      }
    }
  ]
}

示例#

curl -X POST http://localhost:3001/api/mcp/servers/550e8400-e29b-41d4-a716-446655440000/discover \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

MCP 工具#

GET /api/mcp/tools#

列出所有已注册服务器中发现的 MCP 工具。

认证： JWT

响应体#

[
  {
    "id": "uuid",
    "server_id": "uuid",
    "server_name": "jira-tools",
    "name": "search_issues",
    "description": "Search Jira issues by JQL",
    "input_schema": {
      "type": "object",
      "properties": {
        "jql": {"type": "string"}
      },
      "required": ["jql"]
    }
  }
]

示例#

curl http://localhost:3001/api/mcp/tools \
  -H "Authorization: Bearer eyJhbGciOi..."

---

分析#

GET /api/analytics/usage#

获取一段时间内的用量数据（请求数、Token 数）。

认证： JWT

查询参数#

响应体#

{
  "data": [
    {
      "period": "2026-03-27",
      "request_count": 1520,
      "prompt_tokens": 450000,
      "completion_tokens": 120000,
      "total_tokens": 570000
    }
  ]
}

示例#

curl "http://localhost:3001/api/analytics/usage?from=2026-03-01T00:00:00Z&group_by=day" \
  -H "Authorization: Bearer eyJhbGciOi..."

---

GET /api/analytics/usage/stats#

获取聚合的用量统计数据（总计和平均值）。

认证： JWT

响应体#

{
  "total_requests": 45000,
  "total_tokens": 12500000,
  "avg_latency_ms": 850,
  "models": {
    "gpt-4o": {"requests": 30000, "tokens": 9000000},
    "claude-sonnet-4-20250514": {"requests": 15000, "tokens": 3500000}
  }
}

示例#

curl http://localhost:3001/api/analytics/usage/stats \
  -H "Authorization: Bearer eyJhbGciOi..."

---

GET /api/analytics/costs#

获取一段时间内的成本数据。

认证： JWT

查询参数#

响应体#

{
  "data": [
    {
      "period": "2026-03-27",
      "total_cost_usd": 45.20,
      "by_model": {
        "gpt-4o": 32.10,
        "claude-sonnet-4-20250514": 13.10
      }
    }
  ]
}

示例#

curl "http://localhost:3001/api/analytics/costs?from=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer eyJhbGciOi..."

---

GET /api/analytics/costs/stats#

获取聚合的成本统计数据。

认证： JWT

响应体#

{
  "total_cost_usd": 1250.00,
  "avg_daily_cost_usd": 41.67,
  "by_model": {
    "gpt-4o": 890.00,
    "claude-sonnet-4-20250514": 360.00
  }
}

示例#

curl http://localhost:3001/api/analytics/costs/stats \
  -H "Authorization: Bearer eyJhbGciOi..."

---

审计#

GET /api/audit/logs#

搜索审计日志条目。由 ClickHouse 支持 SQL 查询和分析。

认证： JWT（管理员）

查询参数#

响应体#

{
  "total": 2340,
  "offset": 0,
  "limit": 50,
  "entries": [
    {
      "id": "uuid",
      "timestamp": "2026-03-28T09:15:00Z",
      "user_id": "uuid",
      "user_email": "admin@example.com",
      "action": "provider.create",
      "resource_type": "provider",
      "resource_id": "uuid",
      "details": {"name": "openai-prod"},
      "ip_address": "10.0.1.50",
      "user_agent": "Mozilla/5.0..."
    }
  ]
}

常用操作值#

示例#

curl "http://localhost:3001/api/audit/logs?q=provider.create&from=2026-03-01T00:00:00Z&limit=20" \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

访问日志#

查询访问日志#

GET /api/admin/access-logs

Gateway 和 Console 端口的 HTTP 请求日志。

查询参数：

应用日志#

查询应用日志#

GET /api/admin/app-logs

应用运行时追踪日志。

查询参数：

平台日志#

查询平台日志#

GET /api/admin/platform-logs

平台管理操作审计记录。

查询参数：

网关日志#

查询网关日志#

GET /api/gateway/logs

AI API 请求日志，包含模型、Provider、Token 和费用数据。

查询参数：

MCP 日志#

查询 MCP 日志#

GET /api/mcp/logs

MCP 工具调用日志。

查询参数：

---

管理员设置#

GET /api/admin/settings#

获取按类别分组的所有设置。

认证： JWT（管理员）

响应体#

{
  "auth": {
    "jwt_access_ttl_seconds": 900,
    "jwt_refresh_ttl_seconds": 604800
  },
  "cache": {
    "cache_ttl_seconds": 300
  },
  "security": {
    "signature_drift_seconds": 300,
    "nonce_ttl_seconds": 300,
    "redact": {},
    "inspect_tools": {},
    "content": {}
  },
  "budget": {
    "budget_warning_threshold": 0.8,
    "budget_critical_threshold": 0.95
  },
  "keys": {
    "api_key_max_expiry_days": 365,
    "api_key_default_rate_limit_rpm": 60
  },
  "general": {
    "data_retention_days": 30,
    "site_name": "ThinkWatch"
  }
}

示例#

curl http://localhost:3001/api/admin/settings \
  -H "Authorization: Bearer eyJhbGciOi..."

---

PATCH /api/admin/settings#

更新一个或多个设置。设置在持久化之前会进行验证。

认证： JWT（管理员）

请求体#

{
  "settings": {
    "jwt_access_ttl_seconds": 1800,
    "site_name": "My AI Gateway",
    "data_retention_days": 60
  }
}

响应体#

{
  "updated": ["jwt_access_ttl_seconds", "site_name", "data_retention_days"],
  "settings": {
    "jwt_access_ttl_seconds": 1800,
    "site_name": "My AI Gateway",
    "data_retention_days": 60
  }
}

示例#

curl -X PATCH http://localhost:3001/api/admin/settings \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "jwt_access_ttl_seconds": 1800,
      "data_retention_days": 90
    }
  }'

错误响应#

---

GET /api/admin/settings/category/{category}#

获取特定类别的设置。

认证： JWT（管理员）

路径参数#

响应体#

仅返回所请求类别的设置（与 GET /api/admin/settings 中对应部分的结构相同）。

示例#

curl http://localhost:3001/api/admin/settings/category/auth \
  -H "Authorization: Bearer eyJhbGciOi..."

错误响应#

---

注意： 旧版端点 GET /api/admin/settings/system、GET /api/admin/settings/oidc 和 GET /api/admin/settings/audit 仍然可用，作为 GET /api/admin/settings/category/{category} 对应类别的别名。

---

控制台健康检查#

GET /api/health#

详细的健康检查，报告与后端服务的连通性、延迟指标和连接池状态。

认证： 公开

响应体（健康）#

{
  "status": "ok",
  "pg_latency_ms": 2.5,
  "redis_latency_ms": 0.8,
  "clickhouse_latency_ms": 5.1,
  "pool_idle": 8,
  "pool_active": 2,
  "uptime_seconds": 86400,
  "services": {
    "postgres": "ok",
    "redis": "ok",
    "clickhouse": "ok"
  }
}

响应体（降级）#

如果关键依赖（PostgreSQL 或 Redis）不可达，端点返回 HTTP 503：

{
  "status": "degraded",
  "pg_latency_ms": null,
  "redis_latency_ms": 0.8,
  "clickhouse_latency_ms": 5.1,
  "pool_idle": 0,
  "pool_active": 0,
  "uptime_seconds": 86400,
  "services": {
    "postgres": "error",
    "redis": "ok",
    "clickhouse": "ok"
  }
}

示例#

curl http://localhost:3001/api/health