REST API Reference

aisw serve 启动 PocketBase 后端，并挂载自定义 /api/aisw/* 路由与嵌入式 Web UI。

Base URL

http://127.0.0.1:8090

默认仅监听本机。Web UI 入口：GET /

Authentication

自定义 /api/aisw/* 端点无认证，面向本地开发使用（默认 127.0.0.1）。请勿将未鉴权的 serve 暴露到公网。

PocketBase 集合端点为公开只读；匿名 create/update/delete 未启用。

API Key 处理

---

Web UI

GET /
GET /style.css
GET /app.js

嵌入式静态页面（internal/webui/static/），通过 /api/aisw/* 完成 Provider/Profile 管理与预设导入。

---

Discovery

Health Check

GET /api/aisw/health

Response:

{
  "ok": true,
  "service": "innate-aiswitcher"
}

---

Catalog

GET /api/aisw/catalog

返回 agents 与 providers（api_key 已清空）。

---

List Agents

GET /api/aisw/agents

返回全部已 seed 的 agent 记录（只读）。

---

List Presets

GET /api/aisw/presets

返回内置 provider-presets.toml 中的预设列表（与 aisw provider presets 同源）。

---

Providers

List Providers

GET /api/aisw/providers

Get Provider

GET /api/aisw/providers/{slug}

Create Provider

POST /api/aisw/providers
Content-Type: application/json

Body: Provider JSON（slug, name, base_url, api_key, api_protocol, default_model, headers, endpoints, capabilities, notes, active）

Response: 201 Created，api_key 已掩码。

Update Provider

PUT /api/aisw/providers/{slug}
Content-Type: application/json

路径 {slug} 与 body 中的 slug 应对齐。api_key 留空则保留原值。

Delete Provider

DELETE /api/aisw/providers/{slug}

Response:

{ "ok": true }

Import from Preset

POST /api/aisw/providers/from-preset
Content-Type: application/json

Body:

{
  "preset_slug": "deepseek",
  "option_slug": "openai",
  "api_key": "sk-..."
}

根据内置预设与 URL option 生成 provider 并 upsert（与 TUI/CLI 预设投影规则一致）。

List Provider Models

GET /api/aisw/providers/{slug}/models

与 aisw test models {slug} 相同。

Response:

{
  "ok": true,
  "status_code": 200,
  "endpoint": "https://api.example.com/v1/models",
  "models": ["model-a", "model-b"],
  "message": ""
}

连通失败时 HTTP 状态码为 502。

Test Provider

POST /api/aisw/providers/{slug}/test
Content-Type: application/json

与 aisw test provider {slug} 相同。

Body:

{
  "model": "optional-model-override"
}

Response:

{
  "ok": true,
  "status_code": 200,
  "endpoint": "https://api.example.com/v1/chat/completions",
  "message": "{\"id\":\"ok\"}"
}

连通失败时 HTTP 状态码为 502。

---

Profiles

List Profiles

GET /api/aisw/profiles

Create Profile

POST /api/aisw/profiles
Content-Type: application/json

Body: Profile JSON（slug, name, agent, provider, model, default_args, skip_permissions, is_default, config_overrides, env_overrides）

Update Profile

PUT /api/aisw/profiles/{slug}
Content-Type: application/json

Delete Profile

DELETE /api/aisw/profiles/{slug}

Response:

{ "ok": true }

---

PocketBase Collection Endpoints (Read-Only)

标准 PocketBase REST，仅公开读权限：

GET /api/collections/agents/records
GET /api/collections/providers/records
GET /api/collections/profiles/records

providers 集合的 api_key 为 hidden field，响应中不包含。

---

Error Responses

自定义端点错误体格式：

{
  "ok": false,
  "message": "provider not found"
}

PocketBase 集合端点遵循 PocketBase 标准错误格式。

---

CLI to REST Mapping