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
• auth
• 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}
• DELETE /api/admin/workspaces/{workspace_id}
• GET /api/admin/workspaces/{workspace_id}/members
• PATCH /api/admin/workspaces/{workspace_id}/members/{user_id}
• DELETE /api/admin/workspaces/{workspace_id}/members/{user_id}
• GET /api/admin/workspaces/{workspace_id}/invitations
• POST /api/admin/workspaces/{workspace_id}/invitations
• DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}
• GET /api/admin/workspaces/{workspace_id}/export

Контракт:

• POST /invitations возвращает metadata invitation и одноразовый invite_token;
• invite_token доступен только в create-response и не возвращается повторно в list endpoints;
• PATCH /members/{user_id} меняет роль участника;
• DELETE /members/{user_id} удаляет участника из workspace;
• GET /export возвращает JSON snapshot workspace lifecycle-данных;
• DELETE /workspaces/{workspace_id} разрешен только owner.

5.2. Auth and session

• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/session
• GET /api/auth/profile
• PATCH /api/auth/profile
• POST /api/auth/password

Контракт:

• POST /login принимает email и password;
• при успешном логине backend выставляет HttpOnly session cookie;
• GET /session возвращает текущего пользователя и memberships;
• GET /profile возвращает текущего пользователя и memberships для settings UI;
• PATCH /profile обновляет display_name и email текущего пользователя;
• POST /password меняет пароль текущего пользователя после проверки current_password;
• POST /logout инвалидирует текущую session.

5.3. 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.4. 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.5. 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.6. 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.7. 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.8. 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}

Контракт:

• GET /logs поддерживает level, search, source, operation_id, agent_id, period, limit;
• period использует UI-friendly значения 30m, 1h, 6h, 24h, 7d, 30d, 90d, this_month;
• source различает admin_test_run и agent_tool_call;
• GET /usage возвращает summary, timeline, operations, agents одним ответом;
• detail endpoints по operation и agent возвращают rollup для выбранного периода.

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.

Текущая реализация:

• summary и breakdown считаются по invocation_logs;
• materialized usage_rollups остаются совместимым storage-слоем для дальнейшей оптимизации, но не являются единственным source of truth в MVP.

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

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