> ## 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. # Get workflow details by slug or slug@version (runtime) > Returns the full workflow template using its human-readable slug instead of UUID. Identical to GET by ID but allows lookup by the globally unique slug. Pass `slug@version` (for example, `text-to-image@2`) to inspect the workflow JSON and parameter definitions saved for a previous version snapshot. Use the `parameters` array to discover configurable inputs for RunWorkflowBySlug. Accepts JWT Bearer, `sk-` integration credential, or `dk-` device credential. ## OpenAPI ````yaml /api-reference/core-openapi.yaml get /r/workflows/slug/{workflowSlug} 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: /r/workflows/slug/{workflowSlug}: parameters: - $ref: '#/components/parameters/TeamIdHeaderOptional' - $ref: '#/components/parameters/WorkflowSlug' get: tags: - Workflow summary: Get workflow details by slug or slug@version (runtime) description: > Returns the full workflow template using its human-readable slug instead of UUID. Identical to GET by ID but allows lookup by the globally unique slug. Pass `slug@version` (for example, `text-to-image@2`) to inspect the workflow JSON and parameter definitions saved for a previous version snapshot. Use the `parameters` array to discover configurable inputs for RunWorkflowBySlug. Accepts JWT Bearer, `sk-` integration credential, or `dk-` device credential. operationId: getWorkflowRuntimeBySlug responses: '200': description: Workflow details content: application/json: schema: $ref: '#/components/schemas/Workflow' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - bearerAuth: [] - DeviceAuth: [] - ApiKeyAuth: [] 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 WorkflowSlug: name: workflowSlug in: path required: true description: > Workflow slug for runtime lookup. Use `slug` for the latest version or `slug@version` to reference an immutable workflow snapshot, e.g. `text-to-image@2`. schema: type: string pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*(?:@[1-9][0-9]*)?$ maxLength: 128 example: text-to-image@2 schemas: Workflow: type: object description: > Full workflow template details including the workflow JSON and parameter definitions. Note: workflow_json is not returned for API-Key authenticated requests. required: - id - workflow_slug - display_name - version - workflow_status - created_at - updated_at properties: id: type: string format: uuid description: UUID of the workflow. example: 019abc12-8901-7890-abcd-ef1234567895 workflow_slug: type: string description: Globally unique URL-friendly slug for the workflow. example: sd-portrait-v2 display_name: type: string description: Workflow name. example: SD 1.5 Portrait Generator description: type: string description: Workflow description. workflow_json: type: object description: | Complete tool-specific workflow definition. Not returned for API-Key authenticated requests. parameters: type: array description: Configurable parameter definitions. items: $ref: '#/components/schemas/ParameterDef' required_labels: type: array description: Labels required for agent matching. items: type: string example: - gpu - sd15 task_timeout: type: integer description: >- Maximum execution time in seconds after agent ACK. 0 means no timeout. example: 300 max_retries: type: integer description: Maximum number of automatic retries on failure. 0 means no retry. example: 2 preferred_gpu: type: string description: Preferred GPU type for agent matching. example: RTX_4090 default_dispatch_target: type: string enum: - agent - comfy_cloud description: Default compute source for tasks created from this workflow. example: agent min_vram_gb: type: integer description: Minimum GPU VRAM required (decimal GB). 0 means no requirement. example: 24 required_models: type: array description: Model paths the workflow needs in an agent's cache. items: type: string example: - checkpoints/sdxl-base.safetensors tool_type: $ref: '#/components/schemas/ToolType' version: type: integer description: Auto-incrementing version number. Increases by 1 on each update. example: 3 workflow_status: type: string enum: - active - disabled description: | Current workflow status: - `active`: Workflow can accept new task submissions. - `disabled`: New task submissions are rejected. example: active created_at: type: string format: date-time description: When the workflow was created (ISO 8601). example: '2025-01-20T10:00:00Z' updated_at: type: string format: date-time description: When the workflow was last updated (ISO 8601). example: '2025-02-15T14:30:00Z' ParameterDef: type: object description: > Defines a user-configurable parameter. For ComfyUI workflows, node_id and field map to workflow_json[node_id]["inputs"][field]. For Nerfstudio workflows, target_path maps to a dot-separated field in the tool spec (for example, train.max_num_iterations). Note: node_id, field, and target_path are not returned for API-Key authenticated requests. required: - key - type - label properties: key: type: string description: > Unique parameter identifier within this workflow. Used as the key in the RunWorkflowRequest.parameters map when submitting a task. example: prompt node_id: type: string description: > ComfyUI workflow node ID that this parameter targets. Must match a top-level key in workflow_json (e.g. "6" refers to workflow_json["6"]). Not returned for API-Key authenticated requests. example: '6' field: type: string description: > Input field name within the target node's inputs object. The parameter value replaces workflow_json[node_id]["inputs"][field]. Not returned for API-Key authenticated requests. example: text target_path: type: string description: > Dot-separated path within a non-ComfyUI tool spec. Used by Nerfstudio workflows for parameter injection. Not returned for API-Key authenticated requests. example: train.max_num_iterations type: type: string enum: - string - number - boolean - select - file - mask description: > Data type of the parameter value. Determines validation and UI widget: - string: free-text input - number: numeric input (optional min/max) - boolean: true/false toggle - select: dropdown from the options list - file: file upload (use accept to restrict MIME types) - mask: inpainting mask image tied to a file parameter via source_key. The frontend should display a MaskEditor overlay on the source image. The mask is uploaded as a PNG via the same presign flow as file. At runtime the agent composites the mask into the source image's alpha channel so that ComfyUI's LoadImage node outputs the correct MASK tensor. label: type: string description: Human-readable label shown in the UI for this parameter. example: Positive Prompt description: type: string description: Optional help text explaining what this parameter does. required: type: boolean description: >- If true, a value must be provided when running the workflow. Defaults to false. default: description: >- Default value used when the parameter is not provided at run time. Type should match the parameter type. min: type: number format: double description: 'Minimum allowed value (inclusive). Only valid for type: number.' max: type: number format: double description: >- Maximum allowed value (inclusive). Only valid for type: number. Must be >= min. options: type: array description: 'List of allowed values. Required and only valid for type: select.' items: type: string accept: type: array description: >- Allowed MIME type patterns for file uploads. Only valid for type: file or mask. Example: ["image/*", "video/mp4"]. items: type: string source_key: type: string description: > Only valid for type: mask. References the key of another parameter (must be type: file) that provides the source image for the mask editor. The mask and its source image must target the same node_id and field. At runtime the agent composites the mask PNG into the source image's alpha channel before uploading to ComfyUI. example: input_image ToolType: type: string enum: - comfyui - nerfstudio description: | Tool runtime used by this workflow: - `comfyui`: ComfyUI API workflow JSON (default, backward compatible). - `nerfstudio`: Nerfstudio 3DGS pipeline spec. example: comfyui ErrorResponse: type: object required: - error_message properties: error_message: type: string description: Human-readable error message describing what went wrong. example: resource not found responses: BadRequest: description: >- Invalid request: missing required fields, validation failure, or malformed input. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: 'Authentication failed: missing, expired, or invalid JWT/API key.' 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' NotFound: description: 'Resource not found: the specified ID or slug does not exist.' 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. ApiKeyAuth: type: http scheme: bearer description: > Integration credential (Bearer sk-...). Team-scoped, no user identity, bypasses the authorization layer. Full runtime access on `/r/*` (including container invoke and proxy) and the Web MCP endpoint. **Not accepted on management endpoints** — those need a user-bearing credential (JWT or `DeviceAuth`). Team scope is taken from the credential; `X-Team-ID` is ignored. ````