crank/docs/admin-api.md

# 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`
- `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": {}
  }'
```

## 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` - внутренняя ошибка.