openapi: 3.0.0
info:
title: Mitosis API
description: |
Mitosis is a unified distributed transport evaluation framework that provides REST API endpoints
for managing users, groups, workers, and tasks in a distributed computing environment.
## Authentication
Most endpoints require JWT bearer token authentication. Get a token by calling `/login` with
valid credentials.
## API Structure
- `/auth` - User authentication status
- `/login` - User login
- `/users` - User management
- `/groups` - Group management and file attachments
- `/workers` - Worker registration and management
- `/tasks` - Task submission and monitoring
- `/admin` - Administrative operations (admin users only)
- `/health` - Service health check
- `/redis` - Redis connection information
version: 0.6.0
contact:
name: Mitosis
url: https://github.com/stack-rs/mitosis
license:
name: Apache 2.0
url: https://github.com/stack-rs/mitosis/blob/main/LICENSE
servers:
- url: http://localhost:5000
description: Local development server
- url: https://api.mitosis.example.com
description: Production server
paths:
/health:
get:
summary: Health check
description: Check if the Mitosis coordinator is running and healthy
operationId: healthCheck
tags:
- Health
responses:
"200":
description: Service is healthy
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
/login:
post:
summary: User login
description: Authenticate user and receive JWT token
operationId: userLogin
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserLoginReq"
responses:
"200":
description: Login successful
content:
application/json:
schema:
$ref: "#/components/schemas/UserLoginResp"
"401":
$ref: "#/components/responses/Unauthorized"
"400":
$ref: "#/components/responses/BadRequest"
/auth:
get:
summary: Get current user
description: Get the username of the currently authenticated user
operationId: userAuth
tags:
- Authentication
security:
- bearerAuth: []
responses:
"200":
description: Username of authenticated user
content:
text/plain:
schema:
type: string
"401":
$ref: "#/components/responses/Unauthorized"
/redis:
get:
summary: Get Redis connection info
description: Get Redis connection URL for real-time task monitoring
operationId: getRedisConnectionInfo
tags:
- Pubsub
security:
- bearerAuth: []
responses:
"200":
description: Redis connection information
content:
application/json:
schema:
$ref: "#/components/schemas/RedisConnectionInfo"
"401":
$ref: "#/components/responses/Unauthorized"
/users/{username}/password:
post:
summary: Change user password
description: Change the password for a user (own account only unless admin)
operationId: changePassword
tags:
- Users
security:
- bearerAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
example: johndoe
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserChangePasswordReq"
responses:
"200":
description: Password changed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/UserChangePasswordResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/users/groups:
get:
summary: Query user groups
description: Get all groups the authenticated user has access to
operationId: queryUserGroups
tags:
- Users
security:
- bearerAuth: []
responses:
"200":
description: User groups with roles
content:
application/json:
schema:
$ref: "#/components/schemas/GroupsQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
/groups:
post:
summary: Create group
description: Create a new group (user becomes admin of the group)
operationId: createGroup
tags:
- Groups
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateGroupReq"
responses:
"200":
description: Group created successfully
"401":
$ref: "#/components/responses/Unauthorized"
"409":
$ref: "#/components/responses/Conflict"
/groups/{group_name}:
get:
summary: Get group information
description: Get detailed information about a specific group
operationId: getGroup
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
example: research-team
responses:
"200":
description: Group information
content:
application/json:
schema:
$ref: "#/components/schemas/GroupQueryInfo"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/groups/{group_name}/users:
put:
summary: Update user group roles
description: Add users to group or update their roles
operationId: updateUserGroup
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateUserGroupRoleReq"
responses:
"200":
description: User roles updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
delete:
summary: Remove users from group (query params)
description: Remove users from the group using query parameters
operationId: removeUserGroupParams
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
- name: users
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
description: Comma-separated list of usernames to remove
responses:
"200":
description: Users removed successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/groups/{group_name}/attachments:
post:
summary: Upload group attachment
description: Upload a file to the group's shared storage
operationId: uploadAttachment
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UploadAttachmentReq"
responses:
"200":
description: Upload URL generated
content:
application/json:
schema:
$ref: "#/components/schemas/UploadAttachmentResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/groups/{group_name}/attachments/query:
post:
summary: Query group attachments
description: List attachments in the group with optional filtering
operationId: queryAttachments
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsQueryReq"
responses:
"200":
description: List of attachments
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/groups/{group_name}/attachments/{key}:
get:
summary: Get attachment metadata
description: Get metadata for a specific attachment
operationId: queryAttachment
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
- name: key
in: path
required: true
schema:
type: string
style: simple
explode: false
responses:
"200":
description: Attachment metadata
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentMetadata"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
delete:
summary: Delete attachment
description: Delete a file from group's shared storage
operationId: deleteAttachment
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
- name: key
in: path
required: true
schema:
type: string
style: simple
explode: false
responses:
"200":
description: Attachment deleted successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/groups/{group_name}/download/attachments/{key}:
get:
summary: Download attachment
description: Get download URL for an attachment
operationId: downloadAttachment
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
- name: key
in: path
required: true
schema:
type: string
style: simple
explode: false
responses:
"302":
description: Redirect to download URL
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/groups/{group_name}/download/attachments:
post:
summary: Batch download attachments by filter
description: Get download URLs for group attachments matching filter criteria
operationId: batchDownloadAttachmentsByFilter
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDownloadByFilterReq"
responses:
"200":
description: List of attachment download URLs
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDownloadListResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/groups/{group_name}/download/attachments/list:
post:
summary: Batch download attachments by keys
description: Get download URLs for group attachments by specific keys
operationId: batchDownloadAttachmentsByKeys
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDownloadByKeysReq"
responses:
"200":
description: List of attachment download URLs
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDownloadListResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/groups/{group_name}/delete/attachments:
post:
summary: Batch delete attachments by filter
description: Delete group attachments matching filter criteria
operationId: batchDeleteAttachmentsByFilter
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDeleteByFilterReq"
responses:
"200":
description: Attachment deletion results
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDeleteByFilterResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/groups/{group_name}/delete/attachments/list:
post:
summary: Batch delete attachments by keys
description: Delete group attachments by specific keys
operationId: batchDeleteAttachmentsByKeys
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDeleteByKeysReq"
responses:
"200":
description: Attachment deletion results
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentsDeleteByKeysResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/workers:
post:
summary: Register worker
description: Register a new worker with the coordinator
operationId: registerWorker
tags:
- Workers
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RegisterWorkerReq"
responses:
"200":
description: Worker registered successfully
content:
application/json:
schema:
$ref: "#/components/schemas/RegisterWorkerResp"
"401":
$ref: "#/components/responses/Unauthorized"
delete:
summary: Unregister worker
description: Unregister worker (worker auth required)
operationId: unregisterWorker
tags:
- Workers
security:
- workerAuth: []
responses:
"200":
description: Worker unregistered successfully
"401":
$ref: "#/components/responses/Unauthorized"
/workers/query:
post:
summary: Query workers
description: List workers with optional filtering
operationId: queryWorkers
tags:
- Workers
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersQueryReq"
responses:
"200":
description: List of workers
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
/workers/shutdown:
post:
summary: Batch shutdown workers
description: Shutdown multiple workers by filter criteria
operationId: shutdownWorkersByFilter
tags:
- Workers
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersShutdownByFilterReq"
responses:
"200":
description: Workers shutdown successfully
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersShutdownByFilterResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/workers/shutdown/list:
post:
summary: Batch shutdown workers by UUIDs
description: Shutdown multiple workers by specific UUIDs
operationId: shutdownWorkersByUuids
tags:
- Workers
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersShutdownByUuidsReq"
responses:
"200":
description: Workers shutdown successfully
content:
application/json:
schema:
$ref: "#/components/schemas/WorkersShutdownByUuidsResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/workers/{uuid}:
get:
summary: Get worker information
description: Get detailed information about a specific worker
operationId: getWorker
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Worker information
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
delete:
summary: Shutdown worker
description: Request worker shutdown
operationId: shutdownWorker
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: op
in: query
required: false
schema:
type: string
enum:
- graceful
- force
description: |
Worker shutdown operation:
- Graceful: Wait for current task to complete
- Force: Stop immediately
responses:
"200":
description: Shutdown request sent
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/workers/{uuid}/tags:
put:
summary: Update worker tags
description: Replace worker's tags
operationId: updateWorkerTags
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReplaceWorkerTagsReq"
responses:
"200":
description: Tags updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/workers/{uuid}/labels:
put:
summary: Update worker labels
description: Replace worker's labels
operationId: updateWorkerLabels
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReplaceWorkerLabelsReq"
responses:
"200":
description: Tags updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/workers/{uuid}/groups:
put:
summary: Update worker group roles
description: Add groups to worker or update their roles
operationId: updateWorkerGroups
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateGroupWorkerRoleReq"
responses:
"200":
description: Group roles updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
delete:
summary: Remove worker group roles (query params)
description: Remove groups from worker using query parameters
operationId: removeWorkerGroupsParams
tags:
- Workers
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: groups
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
description: Comma-separated list of group names to remove
responses:
"200":
description: Groups removed successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/workers/heartbeat:
post:
summary: Worker heartbeat
description: Worker sends heartbeat to coordinator
operationId: workerHeartbeat
tags:
- Workers
security:
- workerAuth: []
responses:
"200":
description: Heartbeat received
"401":
$ref: "#/components/responses/Unauthorized"
/workers/tasks:
get:
summary: Fetch task for worker
description: Worker fetches next available task
operationId: fetchTask
tags:
- Workers
security:
- workerAuth: []
responses:
"200":
description: Task assigned to worker
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTaskResp"
"204":
description: No tasks available
"401":
$ref: "#/components/responses/Unauthorized"
post:
summary: Report task status
description: Worker reports task execution status
operationId: reportTask
tags:
- Workers
security:
- workerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReportTaskReq"
responses:
"200":
description: Status reported successfully
content:
application/json:
schema:
$ref: "#/components/schemas/ReportTaskResp"
"401":
$ref: "#/components/responses/Unauthorized"
/workers/tasks/{uuid}:
get:
summary: Get task details for worker
description: Worker queries task details
operationId: getTaskForWorker
tags:
- Workers
security:
- workerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Task details
content:
application/json:
schema:
$ref: "#/components/schemas/WorkerTaskResp"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/workers/tasks/{uuid}/artifacts/{content_type}:
get:
summary: Download task artifact for worker
description: Worker downloads task artifacts
operationId: downloadTaskArtifactForWorker
tags:
- Workers
security:
- workerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: content_type
in: path
required: true
schema:
$ref: "#/components/schemas/ArtifactContentType"
responses:
"302":
description: Redirect to download URL
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/workers/tasks/{uuid}/attachments/{key}:
get:
summary: Download attachment for worker
description: Worker downloads group attachments needed for task
operationId: downloadAttachmentForWorker
tags:
- Workers
security:
- workerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: key
in: path
required: true
schema:
type: string
style: simple
explode: false
responses:
"302":
description: Redirect to download URL
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/tasks:
post:
summary: Submit task
description: Submit a new task for execution
operationId: submitTask
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SubmitTaskReq"
responses:
"200":
description: Task submitted successfully
content:
application/json:
schema:
$ref: "#/components/schemas/SubmitTaskResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/query:
post:
summary: Query tasks
description: List tasks with optional filtering
operationId: queryTasks
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TasksQueryReq"
responses:
"200":
description: List of tasks
content:
application/json:
schema:
$ref: "#/components/schemas/TasksQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
/tasks/cancel:
post:
summary: Batch cancel tasks
description: Cancel multiple tasks by filter criteria
operationId: cancelTasksByFilter
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TasksCancelByFilterReq"
responses:
"200":
description: Tasks cancelled successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TasksCancelByFilterResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/cancel/list:
post:
summary: Batch cancel tasks by UUIDs
description: Cancel multiple tasks by specific UUIDs
operationId: cancelTasksByUuids
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TasksCancelByUuidsReq"
responses:
"200":
description: Tasks cancelled successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TasksCancelByUuidsResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/download/artifacts:
post:
summary: Batch download artifacts by filter
description: Get download URLs for task artifacts matching filter criteria
operationId: batchDownloadArtifactsByFilter
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDownloadByFilterReq"
responses:
"200":
description: List of artifact download URLs
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDownloadListResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/download/artifacts/list:
post:
summary: Batch download artifacts by UUIDs
description: Get download URLs for task artifacts by specific UUIDs
operationId: batchDownloadArtifactsByUuids
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDownloadByUuidsReq"
responses:
"200":
description: List of artifact download URLs
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDownloadListResp"
"401":
$ref: "#/components/responses/Unauthorized"
/tasks/delete/artifacts:
post:
summary: Batch delete artifacts by filter
description: Delete task artifacts matching filter criteria
operationId: batchDeleteArtifactsByFilter
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDeleteByFilterReq"
responses:
"200":
description: Artifact deletion results
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDeleteByFilterResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/delete/artifacts/list:
post:
summary: Batch delete artifacts by UUIDs
description: Delete task artifacts by specific UUIDs
operationId: batchDeleteArtifactsByUuids
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDeleteByUuidsReq"
responses:
"200":
description: Artifact deletion results
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactsDeleteByUuidsResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/submit:
post:
summary: Batch submit tasks
description: Submit multiple tasks at once
operationId: batchSubmitTasks
tags:
- Tasks
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TasksSubmitReq"
responses:
"200":
description: List of submitted task responses
content:
application/json:
schema:
$ref: "#/components/schemas/TasksSubmitResp"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/tasks/{uuid}:
get:
summary: Get task information
description: Get detailed information about a specific task
operationId: getTask
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Task information
content:
application/json:
schema:
$ref: "#/components/schemas/TaskQueryResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
put:
summary: Update task
description: Modify task configuration (only for pending tasks)
operationId: updateTask
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChangeTaskReq"
responses:
"200":
description: Task updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
$ref: "#/components/responses/Conflict"
delete:
summary: Cancel task
description: Cancel a pending or running task
operationId: cancelTask
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Task cancelled successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
$ref: "#/components/responses/Conflict"
/tasks/{uuid}/labels:
put:
summary: Update task labels
description: Replace task labels
operationId: updateTaskLabels
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateTaskLabelsReq"
responses:
"200":
description: Labels updated successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/tasks/{uuid}/artifacts:
post:
summary: Upload task artifact
description: Get upload URL for task artifacts
operationId: uploadTaskArtifact
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UploadArtifactReq"
responses:
"200":
description: Upload URL generated
content:
application/json:
schema:
$ref: "#/components/schemas/UploadArtifactResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/tasks/{uuid}/artifacts/{content_type}:
delete:
summary: Delete task artifact
description: Delete a task artifact
operationId: deleteTaskArtifact
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: content_type
in: path
required: true
schema:
$ref: "#/components/schemas/ArtifactContentType"
responses:
"200":
description: Artifact deleted successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/tasks/{uuid}/download/artifacts/{content_type}:
get:
summary: Download task artifact
description: Get download URL for task artifacts
operationId: downloadTaskArtifact
tags:
- Tasks
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: content_type
in: path
required: true
schema:
$ref: "#/components/schemas/ArtifactContentType"
responses:
"302":
description: Redirect to download URL
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/users:
post:
summary: Create user (Admin)
description: Create a new user account (admin only)
operationId: adminCreateUser
tags:
- Admin
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserReq"
responses:
"200":
description: User created successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
/admin/users/{username}:
delete:
summary: Delete user (Admin)
description: Mark user as deleted (admin only)
operationId: adminDeleteUser
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
responses:
"200":
description: User deleted successfully
content:
application/json:
schema:
$ref: "#/components/schemas/UserStateResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/users/{username}/password:
post:
summary: Change user password (Admin)
description: Change password for any user (admin only)
operationId: adminChangeUserPassword
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AdminChangePasswordReq"
responses:
"200":
description: Password changed successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/users/{username}/group-quota:
post:
summary: Change user group quota (Admin)
description: Change the group quota for a user (admin only)
operationId: adminChangeUserGroupQuota
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
example: johndoe
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChangeUserGroupQuota"
responses:
"200":
description: User group quota changed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/UserGroupQuotaResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/users/{username}/state:
post:
summary: Change user state (Admin)
description: Change user state (active/locked/deleted) (admin only)
operationId: adminChangeUserState
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: username
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChangeUserStateReq"
responses:
"200":
description: User state changed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/UserStateResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/groups/{group_name}/storage-quota:
post:
summary: Change group storage quota (Admin)
description: Update storage quota for a group (admin only)
operationId: adminChangeGroupStorageQuota
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChangeGroupStorageQuotaReq"
responses:
"200":
description: Storage quota updated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/GroupStorageQuotaResp"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/workers/{uuid}/:
delete:
summary: Shutdown worker (Admin)
description: Force shutdown a worker (admin only)
operationId: adminShutdownWorker
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: op
in: query
required: false
schema:
type: string
enum:
- graceful
- force
description: |
Worker shutdown operation:
- Graceful: Wait for current task to complete
- Force: Stop immediately
responses:
"200":
description: Worker shutdown initiated
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/groups/{group_name}/attachments/{key}:
delete:
summary: Delete group attachment (Admin)
description: Delete any group attachment (admin only)
operationId: adminDeleteAttachment
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: group_name
in: path
required: true
schema:
type: string
- name: key
in: path
required: true
schema:
type: string
style: simple
explode: false
responses:
"200":
description: Attachment deleted successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/tasks/{uuid}/artifacts/{content_type}:
delete:
summary: Delete task artifact (Admin)
description: Delete any task artifact (admin only)
operationId: adminDeleteTaskArtifact
tags:
- Admin
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
schema:
type: string
format: uuid
- name: content_type
in: path
required: true
schema:
$ref: "#/components/schemas/ArtifactContentType"
responses:
"200":
description: Artifact deleted successfully
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
/admin/shutdown:
post:
summary: Shutdown coordinator (Admin)
description: Gracefully shutdown the entire coordinator service (admin only)
operationId: adminShutdownCoordinator
tags:
- Admin
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ShutdownReq"
responses:
"200":
description: Shutdown initiated
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token obtained from /login endpoint
workerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token obtained when registering worker
responses:
BadRequest:
description: Bad request - invalid input
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid request format
Unauthorized:
description: Unauthorized - invalid or missing authentication
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid or expired token
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Insufficient permissions
NotFound:
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Resource not found
Conflict:
description: Conflict - resource already exists or state conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Resource already exists
schemas:
ErrorMsg:
type: object
required:
- msg
properties:
msg:
type: string
description: Error message
example: "Task not found"
UserLoginReq:
type: object
required:
- username
- md5_password
properties:
username:
type: string
description: Username
example: johndoe
md5_password:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 16
maxItems: 16
description: MD5 hash of password as byte array
retain:
type: boolean
default: false
description: Whether to retain existing login state
UserLoginResp:
type: object
required:
- token
properties:
token:
type: string
description: JWT authentication token
example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFZDI1NTE5In0...
UserChangePasswordReq:
type: object
required:
- old_md5_password
- new_md5_password
properties:
old_md5_password:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 16
maxItems: 16
description: MD5 hash of current password
new_md5_password:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 16
maxItems: 16
description: MD5 hash of new password
UserChangePasswordResp:
type: object
required:
- token
properties:
token:
type: string
description: New JWT token (password change invalidates old tokens)
AdminChangePasswordReq:
type: object
required:
- new_md5_password
properties:
new_md5_password:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 16
maxItems: 16
description: MD5 hash of new password
CreateUserReq:
type: object
required:
- username
- md5_password
- admin
properties:
username:
type: string
description: Username for the new user
example: johndoe
md5_password:
type: array
items:
type: integer
minimum: 0
maximum: 255
minItems: 16
maxItems: 16
description: MD5 hash of password
admin:
type: boolean
description: Whether the user should have admin privileges
example: false
ChangeUserStateReq:
type: object
required:
- state
properties:
state:
$ref: "#/components/schemas/UserState"
UserStateResp:
type: object
required:
- state
properties:
state:
$ref: "#/components/schemas/UserState"
UserState:
type: string
enum:
- Active
- Locked
- Deleted
description: |
User account state:
- Active: User can log in and use the system
- Locked: User account is temporarily disabled
- Deleted: User account is marked for deletion
GroupState:
type: string
enum:
- Active
- Locked
- Deleted
description: |
Group state:
- Active: Group is active and can be used
- Locked: Group is temporarily disabled
- Deleted: Group is marked for deletion
TaskState:
type: string
enum:
- Pending
- Ready
- Running
- Finished
- Cancelled
- Unknown
description: |
Task execution state:
- Pending: Task is waiting to be processed
- Ready: Task is ready to be picked up by a worker
- Running: Task is currently being executed
- Finished: Task has completed execution
- Cancelled: Task was cancelled
- Unknown: Task state is unknown
TaskExecState:
type: string
enum:
- WorkerExited
- FetchResource
- FetchResourceFinished
- FetchResourceError
- FetchResourceTimeout
- FetchResourceNotFound
- FetchResourceForbidden
- Watch
- WatchFinished
- WatchTimeout
- ExecPending
- ExecSpawned
- ExecFinished
- ExecTimeout
- UploadResult
- UploadFinishedResult
- UploadCancelledResult
- UploadResultFinished
- UploadResultTimeout
- TaskCommitted
- Unknown
description: Detailed task execution state during worker processing
WorkerState:
type: string
enum:
- Normal
- GracefulShutdown
description: |
Worker state:
- Normal: Worker is operating normally
- GracefulShutdown: Worker is shutting down gracefully
UserGroupRole:
type: string
enum:
- Read
- Write
- Admin
description: |
User's role in a group:
- Read: Can view group information and tasks
- Write: Can submit tasks and create workers for the group
- Admin: Can manage group membership and settings
GroupWorkerRole:
type: string
enum:
- Read
- Write
- Admin
description: |
Group's role with a worker:
- Read: Reserved for future use
- Write: Can submit tasks to the worker
- Admin: Can manage worker ACL and settings
ArtifactContentType:
type: string
enum:
- result
- exec-log
- std-log
description: |
Type of task artifact:
- result: Task results from MITO_RESULT_DIR
- exec-log: Execution logs from MITO_EXEC_DIR
- std-log: Standard output and error logs
AttachmentContentType:
type: string
enum:
- application/octet-stream
description: MIME type of group attachment
RedisConnectionInfo:
type: object
properties:
url:
type: string
nullable: true
description: Redis connection URL for clients
example: redis://:password@localhost:6379
CreateGroupReq:
type: object
required:
- group_name
properties:
group_name:
type: string
description: Name of the new group
example: research-team
GroupQueryInfo:
type: object
required:
- group_name
- creator_username
- created_at
- updated_at
- state
- task_count
- storage_quota
- storage_used
- worker_count
properties:
group_name:
type: string
example: research-team
creator_username:
type: string
example: johndoe
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
state:
$ref: "#/components/schemas/GroupState"
task_count:
type: integer
format: int64
description: Number of tasks in the group
example: 42
storage_quota:
type: integer
format: int64
description: Storage quota in bytes
example: 1073741824
storage_used:
type: integer
format: int64
description: Storage currently used in bytes
example: 536870912
worker_count:
type: integer
format: int64
description: Number of workers serving this group
example: 5
users_in_group:
type: object
nullable: true
additionalProperties:
$ref: "#/components/schemas/UserGroupRole"
description: Users in the group and their roles
example:
johndoe: Admin
janedoe: Write
GroupsQueryResp:
type: object
required:
- groups
properties:
groups:
type: object
additionalProperties:
$ref: "#/components/schemas/UserGroupRole"
description: Groups the user has access to and their role
example:
my-group: Admin
research-team: Write
UpdateUserGroupRoleReq:
type: object
required:
- relations
properties:
relations:
type: object
additionalProperties:
$ref: "#/components/schemas/UserGroupRole"
description: Username to role mapping
example:
johndoe: Admin
janedoe: Write
RemoveUserGroupRoleParams:
type: object
properties:
users:
type: array
items:
type: string
description: Usernames to remove from group (query parameter)
example:
- johndoe
- janedoe
ChangeGroupStorageQuotaReq:
type: object
required:
- storage_quota
properties:
storage_quota:
type: string
description: New storage quota (supports units like 1GB, 500MB)
example: 2GB
ChangeUserGroupQuota:
type: object
required:
- group_quota
properties:
group_quota:
type: string
description: |-
New group quota for the user. Supports absolute values or relative operations:
- Absolute: "10" or "=10" (set to 10)
- Relative: "+5" (add 5), "-3" (subtract 3)
example: "+5"
GroupStorageQuotaResp:
type: object
required:
- storage_quota
properties:
storage_quota:
type: integer
format: int64
description: Storage quota in bytes
example: 2147483648
UserGroupQuotaResp:
type: object
required:
- group_quota
properties:
group_quota:
type: integer
format: int32
description: Updated group quota for the user
example: 15
UploadAttachmentReq:
type: object
required:
- key
- content_length
properties:
key:
type: string
description: Unique key for the attachment
example: datasets/experiment-1.tar.gz
content_length:
type: integer
format: uint64
description: Size of file in bytes
example: 1048576
UploadAttachmentResp:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Presigned URL for uploading the file
example: https://s3.example.com/bucket/path?signature=...
AttachmentMetadata:
type: object
required:
- content_type
- size
- created_at
- updated_at
properties:
content_type:
$ref: "#/components/schemas/AttachmentContentType"
size:
type: integer
format: int64
description: File size in bytes
example: 1048576
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
AttachmentsQueryReq:
type: object
properties:
key:
type: string
nullable: true
description: Filter attachments by part of the key
example: datasets/
limit:
type: integer
format: uint64
nullable: true
description: Maximum number of results
example: 50
offset:
type: integer
format: uint64
nullable: true
description: Offset for pagination
example: 0
count:
type: boolean
description: Whether to return total count
default: false
AttachmentQueryInfo:
type: object
required:
- key
- content_type
- size
- created_at
- updated_at
properties:
key:
type: string
example: datasets/experiment-1.tar.gz
content_type:
$ref: "#/components/schemas/AttachmentContentType"
size:
type: integer
format: int64
example: 1048576
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
AttachmentsQueryResp:
type: object
required:
- count
- attachments
- group_name
properties:
count:
type: integer
format: uint64
description: Total number of attachments (if count=true)
example: 25
attachments:
type: array
items:
$ref: "#/components/schemas/AttachmentQueryInfo"
group_name:
type: string
example: research-team
RegisterWorkerReq:
type: object
required:
- tags
- groups
properties:
tags:
type: array
items:
type: string
description: Worker capability tags
example:
- gpu
- cuda
- python
groups:
type: array
items:
type: string
description: Groups this worker can serve
example:
- research-team
- ml-group
lifetime:
type: string
nullable: true
description: Worker lifetime (e.g. "7d", "1h")
example: 7d
RegisterWorkerResp:
type: object
required:
- worker_id
- token
properties:
worker_id:
type: string
format: uuid
description: Unique worker identifier
example: 123e4567-e89b-12d3-a456-426614174000
token:
type: string
description: JWT token for worker authentication
redis_url:
type: string
nullable: true
description: Redis URL for worker notifications
example: redis://:password@localhost:6379
WorkersQueryReq:
type: object
properties:
group_name:
type: string
nullable: true
description: Filter by group name
example: research-team
role:
type: array
items:
$ref: "#/components/schemas/GroupWorkerRole"
nullable: true
description: Filter by group roles
tags:
type: array
items:
type: string
nullable: true
description: Filter by worker tags
example:
- gpu
- python
labels:
type: array
items:
type: string
nullable: true
description: Filter by worker labels
example:
- production
- us-west-2
creator_username:
type: string
nullable: true
description: Filter by creator username
example: johndoe
count:
type: boolean
description: Whether to return total count
default: false
WorkerQueryInfo:
type: object
required:
- worker_id
- creator_username
- tags
- labels
- created_at
- updated_at
- state
- last_heartbeat
properties:
worker_id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
creator_username:
type: string
example: johndoe
tags:
type: array
items:
type: string
example:
- gpu
- python
labels:
type: array
items:
type: string
description: Worker labels for organization and querying
example:
- production
- us-west-2
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
state:
$ref: "#/components/schemas/WorkerState"
last_heartbeat:
type: string
format: date-time
description: When worker last sent heartbeat
example: "2024-01-15T10:35:00Z"
assigned_task_id:
type: string
format: uuid
nullable: true
description: Currently assigned task UUID
example: 456e7890-e89b-12d3-a456-426614174111
WorkerQueryResp:
type: object
required:
- info
- groups
properties:
info:
$ref: "#/components/schemas/WorkerQueryInfo"
groups:
type: object
additionalProperties:
$ref: "#/components/schemas/GroupWorkerRole"
description: Groups this worker serves and their roles
example:
research-team: Write
ml-group: Admin
WorkersQueryResp:
type: object
required:
- count
- workers
- group_name
properties:
count:
type: integer
format: uint64
description: Total number of workers (if count=true)
example: 5
workers:
type: array
items:
$ref: "#/components/schemas/WorkerQueryInfo"
group_name:
type: string
example: research-team
ReplaceWorkerTagsReq:
type: object
required:
- tags
properties:
tags:
type: array
items:
type: string
description: New set of worker tags
example:
- gpu
- cuda
- tensorflow
ReplaceWorkerLabelsReq:
type: object
required:
- labels
properties:
labels:
type: array
items:
type: string
description: New set of worker labels
example:
- gpu
- cuda
- tensorflow
UpdateGroupWorkerRoleReq:
type: object
required:
- relations
properties:
relations:
type: object
additionalProperties:
$ref: "#/components/schemas/GroupWorkerRole"
description: Group to role mapping
example:
research-team: Write
ml-group: Admin
RemoveGroupWorkerRoleParams:
type: object
properties:
groups:
type: array
items:
type: string
description: Groups to remove from worker (query parameter)
example:
- old-group
- deprecated-group
TaskSpec:
type: object
required:
- args
properties:
args:
type: array
items:
type: string
description: Command and arguments to execute
example:
- python3
- train.py
- --epochs
- "100"
envs:
type: object
additionalProperties:
type: string
description: Environment variables
example:
CUDA_VISIBLE_DEVICES: "0,1"
PYTHONPATH: "/workspace"
resources:
type: array
items:
$ref: "#/components/schemas/RemoteResourceDownload"
description: Resources to download before execution
terminal_output:
type: boolean
default: false
description: Whether to capture stdout/stderr
watch:
type: array
items:
oneOf:
- type: string
format: uuid
- $ref: "#/components/schemas/TaskExecState"
minItems: 2
maxItems: 2
nullable: true
description: Watch another task until it reaches specified state
RemoteResourceDownload:
type: object
required:
- remote_file
- local_path
properties:
remote_file:
$ref: "#/components/schemas/RemoteResource"
local_path:
type: string
description: Local path to save the downloaded resource
example: data/dataset.tar.gz
RemoteResource:
type: object
oneOf:
- type: object
required:
- Artifact
properties:
Artifact:
type: object
required:
- uuid
- content_type
properties:
uuid:
type: string
format: uuid
content_type:
$ref: "#/components/schemas/ArtifactContentType"
- type: object
required:
- Attachment
properties:
Attachment:
type: object
required:
- key
properties:
key:
type: string
description: |
Remote resource reference:
- Artifact: Reference to a task artifact
- Attachment: Reference to a group attachment
SubmitTaskReq:
type: object
required:
- group_name
- tags
- labels
- timeout
- priority
- task_spec
properties:
group_name:
type: string
description: Target group for task execution
example: research-team
tags:
type: array
items:
type: string
description: Required worker tags for task execution
example:
- gpu
- python
labels:
type: array
items:
type: string
description: Labels for task organization and querying
example:
- experiment-1
- training
timeout:
type: string
description: Task timeout duration (e.g. "1h", "30m")
example: 2h
priority:
type: integer
format: int32
description: Task priority (higher = more important)
example: 10
task_spec:
$ref: "#/components/schemas/TaskSpec"
SubmitTaskResp:
type: object
required:
- task_id
- uuid
properties:
task_id:
type: integer
format: int64
description: Internal task ID
example: 12345
uuid:
type: string
format: uuid
description: Unique task identifier
example: 789e0123-e89b-12d3-a456-426614174222
ChangeTaskReq:
type: object
properties:
tags:
type: array
items:
type: string
nullable: true
description: Update required worker tags
timeout:
type: string
nullable: true
description: Update task timeout
example: 3h
priority:
type: integer
format: int32
nullable: true
description: Update task priority
task_spec:
$ref: "#/components/schemas/TaskSpec"
nullable: true
description: Update task specification
UpdateTaskLabelsReq:
type: object
required:
- labels
properties:
labels:
type: array
items:
type: string
description: New set of labels (replaces existing)
example:
- experiment-2
- validation
TaskResultSpec:
type: object
required:
- exit_status
properties:
exit_status:
type: integer
format: int32
description: Process exit code
example: 0
msg:
$ref: "#/components/schemas/TaskResultMessage"
nullable: true
description: Optional result message for failures
TaskResultMessage:
type: string
enum:
- FetchResourceTimeout
- ExecTimeout
- UploadResultTimeout
- ResourceNotFound
- ResourceForbidden
- WatchTimeout
- UserCancellation
- SubmitNewTaskFailed
description: |
Task failure reason:
- FetchResourceTimeout: Timeout downloading resources
- ExecTimeout: Task execution timeout
- UploadResultTimeout: Timeout uploading results
- ResourceNotFound: Required resource not found
- ResourceForbidden: Access denied to resource
- WatchTimeout: Watched task timeout
- UserCancellation: Task cancelled by user
- SubmitNewTaskFailed: Failed to submit new task
TasksQueryReq:
type: object
properties:
reporter_uuid:
type: string
format: uuid
nullable: true
description: Filter by reporter worker UUID (archived tasks only)
creator_usernames:
type: array
items:
type: string
nullable: true
description: Filter by task creators
example:
- johndoe
- janedoe
group_name:
type: string
nullable: true
description: Filter by group name
example: research-team
tags:
type: array
items:
type: string
nullable: true
description: Filter by task tags
example:
- gpu
- training
labels:
type: array
items:
type: string
nullable: true
description: Filter by task labels
example:
- experiment-1
states:
type: array
items:
$ref: "#/components/schemas/TaskState"
nullable: true
description: Filter by task states
exit_status:
type: string
nullable: true
description: Filter by exit status (e.g. "0", "!=0")
example: "0"
priority:
type: string
nullable: true
description: Filter by priority (e.g. ">5", "<=10")
example: ">5"
limit:
type: integer
format: uint64
nullable: true
description: Maximum number of results
example: 50
offset:
type: integer
format: uint64
nullable: true
description: Offset for pagination
example: 0
count:
type: boolean
description: Whether to return total count
default: false
TaskQueryInfo:
type: object
required:
- uuid
- creator_username
- group_name
- task_id
- tags
- labels
- created_at
- updated_at
- state
- timeout
- priority
- spec
properties:
uuid:
type: string
format: uuid
example: 789e0123-e89b-12d3-a456-426614174222
reporter_uuid:
type: string
format: uuid
nullable: true
description: UUID of the worker who committed the task (archived tasks only)
creator_username:
type: string
example: johndoe
group_name:
type: string
example: research-team
task_id:
type: integer
format: int64
example: 12345
tags:
type: array
items:
type: string
example:
- gpu
- python
labels:
type: array
items:
type: string
example:
- experiment-1
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:35:00Z"
state:
$ref: "#/components/schemas/TaskState"
timeout:
type: integer
format: int64
description: Task timeout in seconds
example: 7200
priority:
type: integer
format: int32
example: 10
spec:
type: object
description: Task specification as JSON
result:
type: object
nullable: true
description: Task result as JSON (if completed)
upstream_task_uuid:
type: string
format: uuid
nullable: true
downstream_task_uuid:
type: string
format: uuid
nullable: true
ParsedTaskQueryInfo:
type: object
required:
- uuid
- creator_username
- group_name
- task_id
- tags
- labels
- created_at
- updated_at
- state
- timeout
- priority
- spec
properties:
uuid:
type: string
format: uuid
reporter_uuid:
type: string
format: uuid
nullable: true
description: UUID of the worker who committed the task (archived tasks only)
creator_username:
type: string
group_name:
type: string
task_id:
type: integer
format: int64
tags:
type: array
items:
type: string
labels:
type: array
items:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
state:
$ref: "#/components/schemas/TaskState"
timeout:
type: integer
format: int64
priority:
type: integer
format: int32
spec:
$ref: "#/components/schemas/TaskSpec"
result:
$ref: "#/components/schemas/TaskResultSpec"
nullable: true
upstream_task_uuid:
type: string
format: uuid
nullable: true
downstream_task_uuid:
type: string
format: uuid
nullable: true
TaskQueryResp:
type: object
required:
- info
- artifacts
properties:
info:
$ref: "#/components/schemas/ParsedTaskQueryInfo"
artifacts:
type: array
items:
$ref: "#/components/schemas/ArtifactQueryResp"
description: Available artifacts for this task
TasksQueryResp:
type: object
required:
- count
- tasks
- group_name
properties:
count:
type: integer
format: uint64
description: Total number of tasks (if count=true)
tasks:
type: array
items:
$ref: "#/components/schemas/TaskQueryInfo"
group_name:
type: string
ArtifactQueryResp:
type: object
required:
- content_type
- size
- created_at
- updated_at
properties:
content_type:
$ref: "#/components/schemas/ArtifactContentType"
size:
type: integer
format: int64
description: Artifact size in bytes
example: 2048576
created_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
example: "2024-01-15T10:30:00Z"
UploadArtifactReq:
type: object
required:
- content_type
- content_length
properties:
content_type:
$ref: "#/components/schemas/ArtifactContentType"
content_length:
type: integer
format: uint64
description: Artifact size in bytes
example: 2048576
UploadArtifactResp:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Presigned URL for uploading the artifact
WorkerTaskResp:
type: object
required:
- id
- uuid
- timeout
- spec
properties:
id:
type: integer
format: int64
description: Internal task ID
uuid:
type: string
format: uuid
description: Task UUID
timeout:
type: string
description: Task timeout duration
example: 2h
spec:
$ref: "#/components/schemas/TaskSpec"
ReportTaskReq:
type: object
required:
- id
- op
properties:
id:
type: integer
format: int64
description: Internal task ID
op:
$ref: "#/components/schemas/ReportTaskOp"
ReportTaskOp:
type: object
oneOf:
- type: string
enum:
- Finish
- type: string
enum:
- Cancel
- type: object
required:
- Commit
properties:
Commit:
$ref: "#/components/schemas/TaskResultSpec"
- type: object
required:
- Upload
properties:
Upload:
type: object
required:
- content_type
- content_length
properties:
content_type:
$ref: "#/components/schemas/ArtifactContentType"
content_length:
type: integer
format: uint64
description: |
Task operation:
- Finish: Task execution finished (no result)
- Cancel: Task was cancelled
- Commit: Commit task result
- Upload: Request upload URL for artifacts
ReportTaskResp:
type: object
properties:
url:
type: string
format: uri
nullable: true
description: Upload URL (only for Upload operations)
ShutdownReq:
type: object
required:
- secret
properties:
secret:
type: string
description: Secret key for shutdown authorization
example: shutdown-secret-123
WorkerShutdownOp:
type: string
enum:
- Graceful
- Force
description: |
Worker shutdown operation type:
- Graceful: Wait for current task to complete
- Force: Stop immediately
TasksCancelByFilterReq:
type: object
properties:
creator_usernames:
type: array
items:
type: string
nullable: true
description: Filter by task creators
group_name:
type: string
nullable: true
description: Filter by group name
tags:
type: array
items:
type: string
nullable: true
description: Filter by task tags
labels:
type: array
items:
type: string
nullable: true
description: Filter by task labels
states:
type: array
items:
$ref: "#/components/schemas/TaskState"
nullable: true
description: Filter by task states
exit_status:
type: string
nullable: true
description: Filter by exit status
priority:
type: string
nullable: true
description: Filter by priority
description: Request to cancel multiple tasks by filter criteria
TasksCancelByFilterResp:
type: object
required:
- cancelled_count
- group_name
properties:
cancelled_count:
type: integer
format: uint64
description: Number of tasks cancelled
example: 15
group_name:
type: string
description: Group name where tasks were cancelled
example: research-team
TasksCancelByUuidsReq:
type: object
required:
- uuids
properties:
uuids:
type: array
items:
type: string
format: uuid
description: List of task UUIDs to cancel
example:
- "550e8400-e29b-41d4-a716-446655440000"
- "550e8400-e29b-41d4-a716-446655440001"
description: Request to cancel multiple tasks by UUIDs
TasksCancelByUuidsResp:
type: object
required:
- cancelled_count
- failed_uuids
properties:
cancelled_count:
type: integer
format: uint64
description: Number of tasks successfully cancelled
example: 10
failed_uuids:
type: array
items:
type: string
format: uuid
description: List of task UUIDs that failed to cancel (not found or no permission)
example:
- "550e8400-e29b-41d4-a716-446655440005"
WorkersShutdownByFilterReq:
type: object
required:
- op
properties:
group_name:
type: string
nullable: true
description: Filter by group name
role:
type: array
items:
$ref: "#/components/schemas/GroupWorkerRole"
nullable: true
description: Filter by group roles
tags:
type: array
items:
type: string
nullable: true
description: Filter by worker tags
labels:
type: array
items:
type: string
nullable: true
description: Filter by worker labels
creator_username:
type: string
nullable: true
description: Filter by creator username
op:
$ref: "#/components/schemas/WorkerShutdownOp"
description: Request to shutdown multiple workers by filter criteria
WorkersShutdownByFilterResp:
type: object
required:
- shutdown_count
- group_name
properties:
shutdown_count:
type: integer
format: uint64
description: Number of workers shutdown
example: 5
group_name:
type: string
description: Group name where workers were shutdown
example: research-team
WorkersShutdownByUuidsReq:
type: object
required:
- uuids
- op
properties:
uuids:
type: array
items:
type: string
format: uuid
description: List of worker UUIDs to shutdown
example:
- "650e8400-e29b-41d4-a716-446655440000"
- "650e8400-e29b-41d4-a716-446655440001"
op:
$ref: "#/components/schemas/WorkerShutdownOp"
description: Request to shutdown multiple workers by UUIDs
WorkersShutdownByUuidsResp:
type: object
required:
- shutdown_count
- failed_uuids
properties:
shutdown_count:
type: integer
format: uint64
description: Number of workers successfully shutdown
example: 8
failed_uuids:
type: array
items:
type: string
format: uuid
description: List of worker UUIDs that failed to shutdown (not found or no permission)
example:
- "650e8400-e29b-41d4-a716-446655440005"
ArtifactsDownloadByFilterReq:
type: object
required:
- content_type
properties:
reporter_uuid:
type: string
format: uuid
nullable: true
description: Filter by reporter worker UUID (archived tasks only)
creator_usernames:
type: array
items:
type: string
nullable: true
description: Filter by task creators
group_name:
type: string
nullable: true
description: Filter by group name
tags:
type: array
items:
type: string
nullable: true
description: Filter by task tags
labels:
type: array
items:
type: string
nullable: true
description: Filter by task labels
states:
type: array
items:
$ref: "#/components/schemas/TaskState"
nullable: true
description: Filter by task states
exit_status:
type: string
nullable: true
description: Filter by exit status
priority:
type: string
nullable: true
description: Filter by priority
content_type:
$ref: "#/components/schemas/ArtifactContentType"
description: Request to batch download artifacts by filter criteria
ArtifactsDownloadByUuidsReq:
type: object
required:
- uuids
- content_type
properties:
uuids:
type: array
items:
type: string
format: uuid
description: List of task UUIDs to download artifacts from
example:
- 789e0123-e89b-12d3-a456-426614174222
- 123e4567-e89b-12d3-a456-426614174000
content_type:
$ref: "#/components/schemas/ArtifactContentType"
description: Request to batch download artifacts by task UUIDs
ArtifactDownloadItem:
type: object
required:
- uuid
- url
- size
properties:
uuid:
type: string
format: uuid
description: Task UUID
example: 789e0123-e89b-12d3-a456-426614174222
url:
type: string
format: uri
description: Presigned download URL
example: https://s3.example.com/bucket/path?signature=...
size:
type: integer
format: int64
description: Artifact size in bytes
example: 2048576
ArtifactsDownloadListResp:
type: object
required:
- downloads
properties:
downloads:
type: array
items:
$ref: "#/components/schemas/ArtifactDownloadItem"
description: List of artifact downloads
AttachmentsDownloadByFilterReq:
type: object
properties:
key:
type: string
nullable: true
description: Filter attachments by key pattern
example: datasets/
limit:
type: integer
format: uint64
nullable: true
description: Maximum number of results
example: 50
offset:
type: integer
format: uint64
nullable: true
description: Offset for pagination
example: 0
description: Request to batch download attachments by filter criteria
AttachmentsDownloadByKeysReq:
type: object
required:
- keys
properties:
keys:
type: array
items:
type: string
description: List of attachment keys to download
example:
- datasets/experiment-1.tar.gz
- models/checkpoint.pth
description: Request to batch download attachments by specific keys
AttachmentDownloadItem:
type: object
required:
- key
- url
- size
properties:
key:
type: string
description: Attachment key
example: datasets/experiment-1.tar.gz
url:
type: string
format: uri
description: Presigned download URL
example: https://s3.example.com/bucket/path?signature=...
size:
type: integer
format: int64
description: Attachment size in bytes
example: 1048576
AttachmentsDownloadListResp:
type: object
required:
- downloads
- group_name
properties:
downloads:
type: array
items:
$ref: "#/components/schemas/AttachmentDownloadItem"
description: List of attachment downloads
group_name:
type: string
description: Group name
example: research-team
ArtifactsDeleteByFilterReq:
type: object
required:
- content_type
properties:
reporter_uuid:
type: string
format: uuid
nullable: true
description: Filter by reporter worker UUID (archived tasks only)
creator_usernames:
type: array
items:
type: string
nullable: true
description: Filter by task creators
group_name:
type: string
nullable: true
description: Filter by group name
tags:
type: array
items:
type: string
nullable: true
description: Filter by task tags
labels:
type: array
items:
type: string
nullable: true
description: Filter by task labels
states:
type: array
items:
$ref: "#/components/schemas/TaskState"
nullable: true
description: Filter by task states
exit_status:
type: string
nullable: true
description: Filter by exit status (e.g., "0", ">0", "<0")
priority:
type: string
nullable: true
description: Filter by priority (e.g., "10", ">5", "<=3")
content_type:
$ref: "#/components/schemas/ArtifactContentType"
ArtifactsDeleteByUuidsReq:
type: object
required:
- uuids
- content_type
properties:
uuids:
type: array
items:
type: string
format: uuid
description: List of task UUIDs
example:
- 550e8400-e29b-41d4-a716-446655440000
content_type:
$ref: "#/components/schemas/ArtifactContentType"
ArtifactsDeleteByFilterResp:
type: object
required:
- deleted_count
properties:
deleted_count:
type: integer
format: uint64
description: Number of artifacts deleted
example: 5
ArtifactsDeleteByUuidsResp:
type: object
required:
- deleted_count
- failed_uuids
properties:
deleted_count:
type: integer
format: uint64
description: Number of artifacts deleted
example: 5
failed_uuids:
type: array
items:
type: string
format: uuid
description: List of UUIDs that failed to delete
example:
- 550e8400-e29b-41d4-a716-446655440001
AttachmentsDeleteByFilterReq:
type: object
properties:
key:
type: string
nullable: true
description: Filter by key pattern (substring match)
limit:
type: integer
format: uint64
nullable: true
description: Maximum number of attachments to delete
offset:
type: integer
format: uint64
nullable: true
description: Offset for pagination
AttachmentsDeleteByKeysReq:
type: object
required:
- keys
properties:
keys:
type: array
items:
type: string
description: List of attachment keys to delete
example:
- data/input.txt
- config/settings.json
AttachmentsDeleteByFilterResp:
type: object
required:
- deleted_count
- group_name
properties:
deleted_count:
type: integer
format: uint64
description: Number of attachments deleted
example: 3
group_name:
type: string
description: Group name
example: research-team
AttachmentsDeleteByKeysResp:
type: object
required:
- deleted_count
- failed_keys
- group_name
properties:
deleted_count:
type: integer
format: uint64
description: Number of attachments deleted
example: 3
failed_keys:
type: array
items:
type: string
description: List of keys that failed to delete
example:
- data/missing.txt
group_name:
type: string
description: Group name
example: research-team
TasksSubmitReq:
type: object
required:
- tasks
properties:
tasks:
type: array
items:
$ref: "#/components/schemas/SubmitTaskReq"
description: List of tasks to submit
TaskSubmitResult:
oneOf:
- type: object
required:
- Ok
properties:
Ok:
$ref: "#/components/schemas/SubmitTaskResp"
description: Successful task submission
- type: object
required:
- Err
properties:
Err:
$ref: "#/components/schemas/ErrorMsg"
description: Failed task submission
description: Result of a single task submission (Ok or Err)
TasksSubmitResp:
type: object
required:
- results
properties:
results:
type: array
items:
$ref: "#/components/schemas/TaskSubmitResult"
description: List of individual task submission results (each is either Ok or Err)
security:
- bearerAuth: []
tags:
- name: Authentication
description: User authentication and session management
- name: Users
description: User account management
- name: Groups
description: Group management and file attachments
- name: Workers
description: Worker registration and management
- name: Tasks
description: Task submission and monitoring
- name: Admin
description: Administrative operations
- name: Health
description: Service health and status
- name: Pubsub
description: Publish or subscribe to task state transition