> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt > Use this file to discover all available pages before exploring further. # List connected agents > Returns agents currently registered for this team via WebSocket. Data is read from the the platform's runtime state (the cache), not from a database. Maximum 500 agents scanned. Supports pagination. ## OpenAPI ````yaml /api-reference/core-openapi.yaml get /agents openapi: 3.0.3 info: title: Cyberun API version: 1.0.0 description: > Multi-tenant GPU orchestration platform for enterprise private deployments. ## Authentication Two authentication families are supported: - **JWT Bearer** (`Authorization: Bearer `) — Used by team owners/admins/members for management endpoints and user sessions. JWT-authenticated requests that operate on a team **must** include the `X-Team-ID` header to select which team the request applies to (a user can belong to multiple teams). - **Credential Bearer** (`Authorization: Bearer `) — Unified machine credential. The credential is always scoped to a single team derived from the credential row, and any `X-Team-ID` header is **ignored**. The three kinds differ in identity and routing: | Kind | Prefix | Identity | Allowed surfaces | | ------------- | ------ | ------------------------- | --- | | `integration` | `sk-` | Team only | Runtime API (`/r/`) + the Web MCP endpoint. Rejected on every management endpoint because the authorization layer needs a user identity and `sk-` has none. | | `agent` | `ak-` | Team only | the platform's WebSocket handshake **only** — rejected by the REST surface at the middleware layer. | | `device` | `dk-` | Team + user (per-device) | Runtime API and scoped management endpoints — behaves like a JWT for the underlying user. Issued by the desktop pairing flow only (`POST /desktop/pair/confirm`). | the authorization layer runs against the user identity carried by JWT and `dk-`. `sk-` and `ak-` bypass the authorization layer; service-layer checks enforce team scope for them. Runtime endpoints under `/r/` accept **JWT (with `X-Team-ID`)**, `sk-`, and `dk-`. `ak-` is rejected at the middleware (it is only meaningful on the the platform's WebSocket handshake). Scoped management endpoints accept **JWT (with `X-Team-ID`)** or `dk-`; `sk-` is rejected on management because the the authorization layer authorize layer requires a user identity. The Web MCP endpoint accepts `sk-` only. Multipart upload endpoints (`/uploads/multipart/*`) remain JWT-only. Credential-bearing callers (`sk-`, `dk-`) should use single-part presign (`POST /r/files/presign`) instead — that returns a vanilla S3 PUT URL (≤ 5 GB by S3, subject to the server's configured request cap; default 500 MB). Files beyond the cap currently require the JWT-only multipart flow. ## Task Lifecycle Tasks follow this state machine: `pending → waiting → queued → running → completed | failed | cancelled`. Submit tasks via workflow run endpoints, poll status via GET /r/tasks/{taskId}, and retrieve results via GET /r/tasks/{taskId}/result. ## Pagination All list endpoints support pagination via `current_page` (default: 1) and `per_page` (default: 20, max: 100) query parameters. Responses include a `page_meta` object with `current_page`, `per_page`, and `total_count`. servers: - url: https://core.cyberun.cloud/api/v1 description: Cyberun Cloud API security: [] tags: - name: Auth description: > Authentication and account lifecycle: register, login, logout, token refresh, password reset, and email verification. - name: User description: | Current user profile management: view and update profile, change password. - name: Team description: > Team management: create, update, delete teams, leave, and transfer ownership. Each user gets a personal team on registration. - name: Member description: | Team member management: list members, update roles, and remove members. - name: Invitation description: > Team invitation management: invite users by email, accept/decline invitations, list pending invitations, and cancel invitations. - name: Credential description: | Unified credential management: integration keys (`sk-`) for programmatic API access, agent keys (`ak-`) for headless workers, and device keys (`dk-`) for paired desktop installs. All three share storage and revocation flow; the `kind` field selects behaviour. - name: DevicePair description: > Desktop device pairing flow. Three endpoints — start (anonymous), confirm (JWT, called from the Cyberun dashboard), poll (anonymous, called from desktop) — exchange a short user-visible code for a `dk-` credential without the user ever typing the secret. - name: Workflow description: > ComfyUI workflow template management: create, update, delete, and list workflow templates with configurable parameters, labels, timeout, and retry settings. - name: Task description: | Task execution and monitoring: submit workflow runs, poll task status, retrieve results, and cancel tasks. Tasks follow the lifecycle: `pending → waiting → queued → running → completed | failed | cancelled`. - name: Webhook description: > Webhook management: register HTTPS endpoints to receive event notifications (task.completed, task.failed) with HMAC-SHA256 signed payloads. - name: Container description: > Container service orchestration: deploy arbitrary Docker containers (vLLM, Ollama, custom services) to agents, manage lifecycle, and proxy HTTP requests through the gateway with load balancing. - name: CloudProvider description: > Cloud compute provider management: configure third-party cloud GPU provider API keys (e.g. ComfyUI Cloud) for teams without local GPU agents, and manage automatic cloud fallback settings. - name: Notifications description: | In-app notification center: list, read, and manage notifications for status changes and system alerts. - name: Agent description: > Agent monitoring: view connected agents for a team, including their status, labels, and current task. Data is read from the the platform's runtime state. - name: Node description: | Custom node management: upload, register, update, and delete ComfyUI custom node packages (zip archives) for team-scoped agents. - name: Model description: | Model management: upload, register, update, and delete AI model files (checkpoints, LoRAs, etc.) for team-scoped agents. - name: File description: > File upload for workflow inputs: request presigned upload URLs to stage files (images, videos, audio) in S3, then reference them as `type: file` parameters when running workflows. - name: Upload description: > Multipart upload support for large files: initiate, presign parts, complete, and abort multipart uploads. Used alongside domain-specific presign endpoints for files exceeding ~100 MB. - name: Server description: | Public server information: registration status and other configuration visible to unauthenticated clients. paths: /agents: get: tags: - Agent summary: List connected agents description: > Returns agents currently registered for this team via WebSocket. Data is read from the the platform's runtime state (the cache), not from a database. Maximum 500 agents scanned. Supports pagination. operationId: listAgents parameters: - $ref: '#/components/parameters/TeamIdHeaderOptional' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Agent list content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '400': $ref: '#/components/responses/BadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': $ref: '#/components/responses/Forbidden' security: - bearerAuth: [] - DeviceAuth: [] components: parameters: TeamIdHeaderOptional: name: X-Team-ID in: header required: false description: | UUID of the team to scope the request to. Used by dual-auth endpoints (runtime + scoped management): - **JWT callers** MUST send it — a user may belong to multiple teams and the runtime cannot otherwise know which one to operate on. Missing header → 400. - **Credential callers** (`sk-`, `dk-`) can omit it because the team is derived from the credential row itself. Any value sent is ignored. schema: type: string format: uuid example: 019abc12-4567-7890-abcd-ef1234567891 Page: name: current_page in: query required: false description: 'Page number to retrieve (1-based). Default: 1.' schema: type: integer minimum: 1 default: 1 example: 1 PerPage: name: per_page in: query required: false description: 'Number of items per page (1–100). Default: 20.' schema: type: integer minimum: 1 maximum: 100 default: 20 example: 20 schemas: AgentListResponse: type: object required: - agent_list - page_meta properties: agent_list: type: array description: Agents registered for this team in the current page. items: $ref: '#/components/schemas/AgentItem' page_meta: $ref: '#/components/schemas/PaginationMeta' ErrorResponse: type: object required: - error_message properties: error_message: type: string description: Human-readable error message describing what went wrong. example: resource not found AgentItem: type: object description: > An agent connected to the platform via WebSocket. Agents execute ComfyUI workflows on behalf of a team. Status and metadata are read from the the platform's runtime state. required: - agent_id - agent_status - agent_labels - last_heartbeat properties: agent_id: type: string description: Unique identifier of the agent (set by the agent on registration). example: gpu-node-01 agent_status: type: string enum: - idle - busy - syncing - tunnel - unhealthy description: > Current agent state: - `idle`: Available to accept new tasks (running_count = 0). - `busy`: Currently executing one or more tasks (running_count > 0). For multi-GPU agents, a `busy` agent may still have available capacity. - `syncing`: Downloading models or updating software — will not accept tasks until complete. - `tunnel`: ComfyUI web tunnel is active — will not accept tasks until tunnel is closed. - `unhealthy`: ComfyUI health check failed — agent will not receive tasks until recovered. example: idle agent_version: type: string description: >- Agent binary version reported via heartbeat (e.g. "0.1.3"). May be empty if the agent has not sent a heartbeat yet. example: 0.1.3 tool: type: string enum: - comfyui - nerfstudio description: > Tool runtime this agent serves. One agent process serves one tool family; multi-tool deployments run multiple agent processes. example: comfyui tool_version: type: string description: > Version of the served tool runtime, reported via heartbeat. Empty until the runtime's first healthcheck completes (or the runtime opts out of version reporting). example: 0.3.13 comfyui_version: type: string deprecated: true description: > Deprecated alias of `tool_version` for ComfyUI agents. Populated only when `tool == "comfyui"`. New clients should read `tool_version`. Removed in a future major version. example: 0.3.13 agent_labels: type: array items: type: string description: > Capability labels declared by the agent at registration. Used for task routing — workflows with `required_labels` will only be dispatched to agents whose labels are a superset of the requirement. example: - gpu - a100 - comfyui gpu_capacity: type: integer description: > Total number of GPU slots this agent can run concurrently. Defaults to 1 for single-GPU or legacy agents. Multi-GPU agents report their actual GPU count. example: 8 running_count: type: integer description: > Number of tasks currently running on this agent. For multi-GPU agents, this can be less than `gpu_capacity`, meaning the agent still has available slots. example: 3 running_tasks: type: array items: type: string description: > IDs of all tasks currently being executed. Empty array if idle. Replaces the legacy `current_task_id` for multi-GPU agents. example: - 019abc12-9012-7890-abcd-ef1234567896 - 019abc12-9012-7890-abcd-ef1234567897 platform_arch: type: string description: > Operating system and architecture of the agent host (e.g. "linux/amd64", "darwin/arm64"). Reported at registration time. example: linux/amd64 sync_phase: type: string description: | Current synchronization phase when agent_status is `syncing`. Possible values: "downloading", "installing", "completed", "failed". Empty string when not syncing. example: downloading sync_detail: type: string description: > Human-readable detail about the current sync operation (e.g. model name being downloaded). Empty string when not syncing. example: Downloading model flux1-dev-fp8 (2.1 GB) sync_percent: type: integer description: > Sync progress percentage (0–100). Only meaningful when agent_status is `syncing`. example: 45 connected_at: type: string format: date-time description: > Timestamp when the agent established its current WebSocket connection to the gateway. Resets on reconnection. example: '2025-02-10T14:00:00Z' tasks_completed: type: integer description: > Total number of tasks completed by this agent since it connected. Resets on reconnection. Useful for monitoring agent productivity. example: 42 current_task_id: type: string description: > Legacy field — ID of a task currently being executed. For multi-GPU agents running multiple tasks, use `running_tasks` instead. Empty string if idle. example: 019abc12-9012-7890-abcd-ef1234567896 last_heartbeat: type: string format: date-time description: >- Last heartbeat timestamp from the agent (ISO 8601). Agents that miss heartbeats are automatically unregistered. example: '2025-02-10T14:30:00Z' system_stats: $ref: '#/components/schemas/AgentSystemStats' PaginationMeta: type: object description: Pagination metadata included in all list responses. required: - current_page - per_page - total_count properties: current_page: type: integer description: The 1-based page number being returned. example: 1 per_page: type: integer description: Number of items per page. example: 20 total_count: type: integer description: Total number of matching items across all pages. example: 42 AgentSystemStats: type: object description: > Host and GPU information reported by the agent from ComfyUI's /system_stats endpoint. Updated every few heartbeats. May be null if the agent hasn't reported stats yet. properties: comfyui_version: type: string description: ComfyUI server version. example: 0.3.10 pytorch_version: type: string description: PyTorch version used by ComfyUI. example: 2.5.1+cu124 os_type: type: string description: Operating system type (e.g. "posix", "nt"). example: posix gpu_devices: type: array description: GPU devices available on the agent host. items: $ref: '#/components/schemas/GPUDeviceInfo' GPUDeviceInfo: type: object description: GPU device information from ComfyUI runtime. required: - device_name - device_type - vram_total - vram_free properties: device_name: type: string description: GPU model name. example: NVIDIA GeForce RTX 4090 device_type: type: string description: Device type (cuda, mps, cpu). example: cuda vram_total: type: integer format: int64 description: Total VRAM in bytes. example: 25769803776 vram_free: type: integer format: int64 description: Free VRAM in bytes. example: 22548578304 responses: BadRequest: description: >- Invalid request: missing required fields, validation failure, or malformed input. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- Insufficient permissions: the authenticated user does not have the required role or the authorization layer policy. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User session JWT (Bearer ). Must be paired with the `X-Team-ID` request header on team-scoped endpoints so the server knows which team's resources to operate on. DeviceAuth: type: http scheme: bearer description: > Device credential (Bearer dk-...) issued by the client device-pair flow (`POST /desktop/pair/confirm`). Carries the confirming user's identity, so it behaves like the user's JWT on team-scoped endpoints — the authorization layer runs against the user. Accepted on runtime + management endpoints. Never accepted on the platform's WebSocket. Team scope is bound at pair time; `X-Team-ID` is ignored. ````