# Admin API

## 1. Назначение документа

Этот документ фиксирует целевые HTTP-контракты административного API, через которое UI управляет workspace, operations, agents, platform access и observability.

## 2. Общие правила API

- все payload по умолчанию в `JSON`;
- import/export конфигурации используют `YAML`;
- все основные ресурсы являются `workspace-scoped`;
- версии operation и agent адресуются явно;
- published operation и published agent - ссылки на конкретные version;
- ошибки валидации возвращаются отдельно от transport errors.

Базовый префикс:

```text
/api/admin
```

## 3. Основные ресурсы

- `workspaces`
- `memberships`
- `invitations`
- `operations`
- `auth-profiles`
- `agents`
- `platform-api-keys`
- `logs`
- `usage`
- `samples`
- `descriptors`
- `config import/export`

## 4. Workspace-scoped routing

Канонический префикс для UI-driven сценариев:

```text
/api/admin/workspaces/{workspace_id}
```

## 5. Группы endpoints

### 5.1. Workspaces and members

- `GET /api/admin/workspaces`
- `POST /api/admin/workspaces`
- `GET /api/admin/workspaces/{workspace_id}`
- `PATCH /api/admin/workspaces/{workspace_id}`
- `GET /api/admin/workspaces/{workspace_id}/members`
- `GET /api/admin/workspaces/{workspace_id}/invitations`
- `POST /api/admin/workspaces/{workspace_id}/invitations`
- `DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}`

Контракт:

- `POST /invitations` возвращает metadata invitation и одноразовый `invite_token`;
- `invite_token` доступен только в create-response и не возвращается повторно в list endpoints.

### 5.2. Operations

- `GET /api/admin/workspaces/{workspace_id}/operations`
- `POST /api/admin/workspaces/{workspace_id}/operations`
- `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`

### 5.3. Samples and descriptors

- `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`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/proto`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/descriptor-set`
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/grpc/services`

### 5.4. Upstream 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}`

### 5.5. 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}/bindings`
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`

### 5.6. Platform API keys

- `GET /api/admin/workspaces/{workspace_id}/platform-api-keys`
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys`
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}/revoke`
- `DELETE /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}`

Контракт:

- `POST /platform-api-keys` возвращает metadata ключа и одноразовый `secret`;
- `secret` доступен только в create-response;
- list endpoints возвращают только metadata, `prefix`, `status`, `scopes` и `last_used_at`.

### 5.7. Observability

- `GET /api/admin/workspaces/{workspace_id}/logs`
- `GET /api/admin/workspaces/{workspace_id}/logs/{log_id}`
- `GET /api/admin/workspaces/{workspace_id}/usage`
- `GET /api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}`
- `GET /api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}`

## 6. Page-to-endpoint mapping

### Operations catalog

Нужны:

- список операций;
- удаление операции;
- edit/open operation;
- publish/archive;
- usage summary для карточек и фильтров.

### Wizard

Нужны:

- create/update version;
- test run;
- samples;
- draft generation;
- gRPC descriptor upload и discovery.

Детальные DTO и response shapes для экранов `Operations` и `Wizard` зафиксированы отдельно в:

- `docs/operations-workspace-contracts.md`

### Agents

Нужны:

- CRUD агентов;
- bindings к operations;
- publish agent;
- выдача MCP endpoint metadata.

### API Keys

Нужны:

- list/create/revoke/delete platform API keys;
- one-time reveal значения ключа при создании.

### Logs

Нужны:

- list logs с фильтрами;
- log detail;
- polling или live refresh strategy.

### Usage

Нужны:

- агрегаты по периодам;
- breakdown по operation;
- breakdown по agent;
- CSV export.

## 7. Принцип совместимости

Если UI расходится с текущим backend, приоритет отдается целевой продуктовой модели, но конфликт должен быть явно разобран в `docs/as-is-to-be.md` до начала реализации.