crank/docs/admin-api.md

Admin API

Admin API используется веб-интерфейсом Crank. Его можно использовать и напрямую для автоматизации настройки.

Base path:

/api/admin

Auth path:

/api/auth

Авторизация

Администратор входит по email и паролю. После входа сервер устанавливает HttpOnly session cookie.

curl -i https://crank.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  --data '{
    "email": "owner@example.com",
    "password": "change-me"
  }'

Дальше используйте cookie из ответа:

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

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}

Пример:

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}

Пример создания:

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

Пример тестового запуска:

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"
    }
  }'

Пример публикации:

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 операции и возвращает рекомендации:

{
  "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:

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}

Пример создания агента:

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}

Пример создания ключа:

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

Пример:

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