303 lines
9.9 KiB
Markdown
303 lines
9.9 KiB
Markdown
# Admin API
|
||
|
||
Admin API используется веб-интерфейсом Crank. Его можно использовать и напрямую для автоматизации настройки.
|
||
|
||
Base path:
|
||
|
||
```text
|
||
/api/admin
|
||
```
|
||
|
||
Auth path:
|
||
|
||
```text
|
||
/api/auth
|
||
```
|
||
|
||
## Авторизация
|
||
|
||
Администратор входит по email и паролю. После входа сервер устанавливает HttpOnly session cookie.
|
||
|
||
```bash
|
||
curl -i https://crank.example.com/api/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"email": "owner@example.com",
|
||
"password": "change-me"
|
||
}'
|
||
```
|
||
|
||
Дальше используйте cookie из ответа:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/auth/session \
|
||
-b 'crank_session=<cookie_value>'
|
||
```
|
||
|
||
Endpoints:
|
||
|
||
- `POST /api/auth/login`
|
||
- `POST /api/auth/logout`
|
||
- `GET /api/auth/session`
|
||
- `GET /api/auth/profile`
|
||
- `PATCH /api/auth/profile`
|
||
- `POST /api/auth/password`
|
||
|
||
## Capabilities
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/capabilities \
|
||
-b 'crank_session=<cookie_value>'
|
||
```
|
||
|
||
Community capabilities:
|
||
|
||
- protocol: `rest`;
|
||
- operation security level: `standard`;
|
||
- machine access: static agent API keys.
|
||
|
||
## Workspaces
|
||
|
||
Community работает с одним workspace.
|
||
|
||
- `GET /api/admin/workspaces`
|
||
- `GET /api/admin/workspaces/{workspace_id}`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}`
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces \
|
||
-b 'crank_session=<cookie_value>'
|
||
```
|
||
|
||
## Upstreams
|
||
|
||
Upstream хранит базовый URL внешнего REST API и необязательные статические заголовки.
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/upstreams`
|
||
- `POST /api/admin/workspaces/{workspace_id}/upstreams`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}/upstreams/{upstream_id}`
|
||
|
||
Пример создания:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/upstreams \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"name": "Frankfurter",
|
||
"base_url": "https://api.frankfurter.dev",
|
||
"static_headers": {},
|
||
"auth_profile_id": null
|
||
}'
|
||
```
|
||
|
||
## Operations
|
||
|
||
Операция описывает один REST endpoint как MCP-инструмент.
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/operations`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/analyze-quality`
|
||
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions`
|
||
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs`
|
||
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/export`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/import`
|
||
|
||
Пример тестового запуска:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/operations/<operation_id>/test-runs \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"version": 1,
|
||
"input": {
|
||
"base": "USD",
|
||
"quote": "EUR"
|
||
}
|
||
}'
|
||
```
|
||
|
||
Пример публикации:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/operations/<operation_id>/publish \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{ "version": 1 }'
|
||
```
|
||
|
||
`analyze-quality` принимает payload операции и возвращает рекомендации:
|
||
|
||
```json
|
||
{
|
||
"blocking": false,
|
||
"findings": [
|
||
{
|
||
"severity": "warning",
|
||
"code": "tool_description_too_short",
|
||
"message": "Описание инструмента слишком короткое.",
|
||
"suggested_action": "Добавьте назначение, условия применения и ожидаемый успешный результат.",
|
||
"field_path": "tool_description.description"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## Samples
|
||
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json`
|
||
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate`
|
||
|
||
Samples используются для генерации схемы, стартового маппинга и сохранения тестовых примеров wizard-а.
|
||
|
||
## Secrets
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/secrets`
|
||
- `POST /api/admin/workspaces/{workspace_id}/secrets`
|
||
- `GET /api/admin/workspaces/{workspace_id}/secrets/{secret_id}`
|
||
- `POST /api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/secrets/{secret_id}`
|
||
|
||
Пример создания token secret:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/secrets \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"name": "production-api-token",
|
||
"kind": "token",
|
||
"value": "secret-token-value"
|
||
}'
|
||
```
|
||
|
||
После создания или ротации API возвращает только metadata. Значение секрета нельзя прочитать повторно.
|
||
|
||
## Auth profiles
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/auth-profiles`
|
||
- `POST /api/admin/workspaces/{workspace_id}/auth-profiles`
|
||
- `GET /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
||
|
||
Auth profile хранит ссылки на secrets и способ применения секрета к REST-запросу.
|
||
|
||
## Agents
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/agents`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents`
|
||
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions`
|
||
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/tool-search/preview`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`
|
||
|
||
Пример создания агента:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/agents \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"slug": "currency-rates",
|
||
"display_name": "Курсы валют",
|
||
"description": "Агент с инструментами для получения курсов валют.",
|
||
"instructions": {},
|
||
"tool_selection_policy": {}
|
||
}'
|
||
```
|
||
|
||
Привязки и политика доступа сохраняются одной атомарной операцией:
|
||
|
||
```json
|
||
{
|
||
"bindings": [
|
||
{
|
||
"operation_id": "op_01",
|
||
"operation_version": 1,
|
||
"tool_name": "create_invoice",
|
||
"tool_title": "Создать счёт",
|
||
"enabled": true
|
||
}
|
||
],
|
||
"tool_selection_policy": {
|
||
"mode": "search",
|
||
"groups": [
|
||
{
|
||
"id": "finance",
|
||
"name": "Расчёты",
|
||
"description": "Счета, платежи и возвраты",
|
||
"tool_names": ["create_invoice"]
|
||
}
|
||
],
|
||
"search": { "max_results": 8 }
|
||
}
|
||
}
|
||
```
|
||
|
||
Старый формат тела из одного массива привязок поддерживается и сохраняет текущую политику агента. Предварительная проверка принимает те же `bindings` и `tool_selection_policy`, а также `query` и необязательный `group_ids`.
|
||
|
||
## Agent API keys
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}/revoke`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys/{key_id}`
|
||
|
||
Пример создания ключа:
|
||
|
||
```bash
|
||
curl https://crank.example.com/api/admin/workspaces/ws_default/agents/<agent_id>/platform-api-keys \
|
||
-b 'crank_session=<cookie_value>' \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"name": "Demo MCP client",
|
||
"scopes": ["read", "write"]
|
||
}'
|
||
```
|
||
|
||
Полное значение ключа доступно только в create response.
|
||
|
||
## Logs и usage
|
||
|
||
- `GET /api/admin/workspaces/{workspace_id}/logs`
|
||
- `GET /api/admin/workspaces/{workspace_id}/usage`
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl 'https://crank.example.com/api/admin/workspaces/ws_default/logs?limit=20' \
|
||
-b 'crank_session=<cookie_value>'
|
||
```
|
||
|
||
## Ошибки
|
||
|
||
Admin API возвращает JSON-ошибки с человекочитаемым сообщением и контекстом, если он доступен.
|
||
|
||
Частые HTTP-коды:
|
||
|
||
- `400` - неверный payload;
|
||
- `401` - нет сессии;
|
||
- `403` - действие запрещено;
|
||
- `404` - сущность не найдена;
|
||
- `409` - конфликт состояния;
|
||
- `429` - rate limit;
|
||
- `500` - внутренняя ошибка.
|