crank/docs/admin-api.md

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.

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

/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 сценариев:

/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 до начала реализации.