Admin Panel API — 2.3 → 2.4 (Integrator Migration Guide)

Breaking Changes Summary
Team Creation / Update — Request Body Restructured
Baremetal Node Logs — Response & Query Params Changed
New Endpoints
Non-Breaking Improvements
Known Documentation Gaps
Migration Checklist

1. Breaking Changes Summary

There are two breaking changes between europa and ariel. All other changes are additive.

Change	Impact	Action Required
`POST /api/team` and `PUT /api/team/{team_id}` — request body restructured	Clients sending flat policy ID fields at the top level receive `400: at least one of general or baremetal policies must be enabled`	Wrap policy IDs under `"general": {...}` and add `"has_general_policies": true`. See Section 2.
`GET /baremetal/node/{id}/logs` response shape and query params changed	Clients reading the `pagination` object break; `page` / `per_page` query params no longer apply	Read `total_count` instead of `pagination`; replace `page`/`per_page` with the `lines` query param. See Section 3.

2. Team Creation / Update — Request Body Restructured BREAKING

POST /api/team and PUT /api/team/{team_id} now require policy IDs to be nested inside a general (or baremetal) object. Sending the old flat structure returns 400.

{ "name": "my-team", "color": "#414141", "description": "", "pricing_policy_id": "uuid-...", "resource_policy_id": "uuid-...", "service_policy_id": "uuid-...", "instance_type_policy_id": "uuid-...", "image_policy_id": "uuid-...", "members": [{ "email": "user@example.com", "role": "uuid-...", "pre_onboard": true }] }

New (ariel) — policies nested under general:

{ "name": "my-team", "color": "#414141", "description": "", "has_general_policies": true, "general": { "pricing_policy_id": "uuid-...", "resource_policy_id": "uuid-...", "service_policy_id": "uuid-...", "instance_type_policy_id": "uuid-...", "image_policy_id": "uuid-..." }, "members": [{ "email": "user@example.com", "role": "uuid-...", "pre_onboard": true }] }

If your integration also provisions baremetal teams, use the baremetal object with "has_baremetal_policies": true in the same way. You may set both has_general_policies and has_baremetal_policies to true simultaneously.

Error you will see without this change

{ "code": 12010004, "message": "failed to create team", "errors": [{ "code": 12110007, "message": "invalid policy id", "field": "has_general_policies", "detail": "at least one of general or baremetal policies must be enabled" }] }

3. Baremetal Node Logs — Response & Query Params Changed BREAKING

GET /api/baremetal/node/{id}/logs switched from a paginated log listing to a "last-N-lines" provision-log tail. Both the query parameters and the 200 response schema changed.

Query parameters — old vs new

release 2.3	release 2.4
`page` (integer), `per_page` (integer)	`lines` (string — number of trailing log lines)

Response body — old vs new

Old (2.3) — BaremetalNodeLogsResponse:

{ "logs": [ { } ], "pagination": { "page": 1, "per_page": 20, "total_items": 134, "total_pages": 7 } }

New (ariel) — BaremetalNodeProvisionLogsResponse:

{ "logs": [ { } ], "total_count": 134 }

The logs[] item schema (BaremetalNodeLogResp) is unchanged. Migration: stop reading .pagination; use the scalar .total_count. If you previously paged through logs with page/per_page, request the desired tail length via lines instead.

4. New Endpoints

Endpoints added in ariel that integrators may want to adopt. (37 routes added in total; the integrator-relevant groups are listed here.)

KVM Cluster Node management (new domain)

A full lifecycle surface for KVM cluster nodes under /api/kvm/node: register / list / get / update / delete, plus actions test-connection, reconcile-tunnels, scan, storage_metrics, cluster, initialise, reset, reboot, scan_interfaces (+ {scan_id} poll), interfaces, network_config (POST/GET/DELETE), ssh_keys, and lifecycle-jobs/{job_id}; plus POST /api/kvm/leader-announce for cluster coordination.

These KVM routes are live in the API but are not yet present in swagger.json — see Section 6. Confirm request/response shapes with the platform team before integrating.

Marketplace

Method	Path	Purpose
GET	`/api/marketplace/oauth-info`	OAuth client/config info for the marketplace link flow.
GET	`/api/marketplace/authorize`	OAuth authorize (render).
POST	`/api/marketplace/authorize/login`	OAuth authorize — login step.
POST	`/api/marketplace/authorize/submit`	OAuth authorize — consent/submit step.
GET	`/api/marketplace/gpu_pools/{id}/active_workers`	Active workers for a published pool (MarketplaceGate + service-account auth).
DELETE	`/api/marketplace/link/history`	Hard-delete revoked link rows (returns settings to never-linked state).
POST	`/api/marketplace/purge-history`	API-to-API purge invoked by mesh on link deletion (revoked-token bearer auth).

Pods & GPUaaS scheduling / rootfs

Method	Path	Purpose
POST	`/api/pods/rootfs`	Rootfs action on a pod.
GET	`/api/pods/rootfs-status`	Rootfs extraction status.
POST	`/api/pods/factory_reset`	Factory-reset a pod.
PUT	`/api/pods/{worker_id}/scheduler-config`	Update a pod's scheduler config.
GET	`/api/gpuaas/pool/{pool_id}/scheduler-config`	Read a pool's scheduler config.
PUT	`/api/gpuaas/pool/{pool_id}/scheduler-config`	Update a pool's scheduler config.
PUT	`/api/gpuaas/pool-workers/rootfs-enable`	Enable rootfs persistence on pool workers.

Regions

Method	Path	Purpose
GET	`/api/regions/{id}/leader-secret`	Fetch a region's leader secret (Secure auth).

5. Non-Breaking Improvements

Existing responses gained additional fields (safe to ignore if unused; no parser changes required). Highlights:

Baremetal subscriptions (BaremetalSubscriptionResp) now include gpu_type, image, image_hash, image_id, instance_type, name, node, os_type, os_version, service_id, workspace_id.
Baremetal images & instance types gained creation_type, description, file_size, hash, is_active, last_used.
Baremetal nodes:BaremetalNodeResp and TransitionBaremetalNodeOpts gained service_status; TestConnectionResp gained status_transition.
Marketplace pools gained gpu_spec_*, region_*, time_quantum_in_sec, utilization_percent, and pool_label.
Regions:Region / CreateRegionReq gained baremetal_enabled.
GPUaaS nodes/pools:rootfs_persistence_capable added across AddNodeGpuaasOpts / GPUaaSNodeDetails / NodeGpuaasResp; GPUaaSPool gained pool_label.
Marketplace unsubscribe:MarketplaceUnsubscribeRequest gained marketplace_subscription_id.
23 new DTO definitions for marketplace pods/volumes, baremetal summaries, GPUaaS team metrics, async operations, and SSH/expose-service results.

6. Known Documentation Gaps

If you generate clients from docs/swagger.json, be aware of these mismatches between the spec and the live API (tracked separately for fix):

The 22 new /api/kvm/* routes are not in swagger — generate against them manually or request shapes from the platform team.
Swagger advertises POST /marketplace/connect, /marketplace/sync, /marketplace/disconnect, but these are not currently routed in the API — do not integrate against them yet.
Swagger lists GET /gpuaas-npu; the live route is GET /gpuaas-npu/all.
The deprecated gpuaas/pool/{id}/publish and /unpublish swagger definitions were removed; publishing is now a marketplace-only flow.

7. Migration Checklist

Update POST /api/team and PUT /api/team/{team_id} clients: move policy IDs into "general": {...} and add "has_general_policies": true.

Update GET /baremetal/node/{id}/logs clients: read total_count instead of the pagination object, and replace page/per_page with the lines query param.

Confirm nothing else in your integration depends on the old flat CreateTeam / UpdateTeam schema or the old BaremetalNodeLogsResponse shape.

(Optional) Adopt new marketplace OAuth/authorize and link-history endpoints if you manage the my.hosted.ai link from your integration.

(Optional) Adopt pod/GPUaaS scheduler-config and rootfs endpoints.

(Optional) Adopt the KVM cluster-node endpoints — but verify shapes out-of-band, as they are not yet in swagger.

Do NOT integrate against /marketplace/connect|sync|disconnect until they are actually routed.