openapi: 3.0.0 info: version: 1.0.0 title: Flamenco manager description: Render Farm manager API contact: name: Flamenco Team url: https://flamenco.io/ license: name: GPLv3 url: https://www.gnu.org/licenses/gpl-3.0.en.html servers: - url: / paths: ## Meta /api/v3/version: summary: Clients can use this to check this is actually a Flamenco server. get: summary: Get the Flamenco version of this Manager operationId: getVersion tags: [meta] responses: "200": description: normal response content: application/json: schema: $ref: "#/components/schemas/FlamencoVersion" /api/v3/configuration: summary: Endpoint for getting configuration of Flamenco Manager. get: summary: Get the configuration of this Manager. operationId: getConfiguration tags: [meta] responses: "200": description: normal response content: application/json: schema: { $ref: "#/components/schemas/ManagerConfiguration" } ## Worker /api/v3/worker/register-worker: summary: Registration of new workers post: summary: Register a new worker operationId: registerWorker tags: [worker] requestBody: description: Worker to register required: true content: application/json: schema: $ref: "#/components/schemas/WorkerRegistration" responses: "200": description: normal response content: application/json: schema: $ref: "#/components/schemas/RegisteredWorker" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/sign-on: summary: Called by Workers to let the Manager know they're ready to work, and to update their metadata. post: summary: Authenticate & sign in the worker. operationId: signOn security: [{ worker_auth: [] }] tags: [worker] requestBody: description: Worker metadata required: true content: application/json: schema: $ref: "#/components/schemas/WorkerSignOn" responses: "200": description: normal response content: application/json: schema: $ref: "#/components/schemas/WorkerStateChange" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/sign-off: summary: Called by Workers to let the Manager know they're going offline. post: summary: Mark the worker as offline operationId: signOff security: [{ worker_auth: [] }] tags: [worker] responses: "204": description: normal response default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/state: summary: Called by Workers to check whether there is any state change requested. get: operationId: workerState security: [{ worker_auth: [] }] tags: [worker] responses: "204": description: no state change requested "200": description: state change requested content: application/json: schema: $ref: "#/components/schemas/WorkerStateChange" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/state-changed: summary: Called by Workers to let the Manager know they've changed status. post: summary: Worker changed state. This could be as acknowledgement of a Manager-requested state change, or in response to worker-local signals. operationId: workerStateChanged security: [{ worker_auth: [] }] tags: [worker] requestBody: description: New worker state required: true content: application/json: schema: $ref: "#/components/schemas/WorkerStateChanged" responses: "204": description: normal response default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/task: summary: Task scheduler endpoint. post: operationId: scheduleTask summary: Obtain a new task to execute security: [{ worker_auth: [] }] tags: [worker] responses: "204": description: No tasks available for this Worker. "200": description: Task to execute. content: application/json: schema: { $ref: "#/components/schemas/AssignedTask" } "403": description: Permission Denied content: application/json: schema: { $ref: "#/components/schemas/SecurityError" } "409": description: Worker is not in the active state, so is not allowed to execute tasks right now. "423": description: Worker cannot obtain new tasks, but must go to another state. content: application/json: schema: $ref: "#/components/schemas/WorkerStateChange" /api/v3/worker/task/{task_id}: summary: Workers send info about task progression here. post: operationId: taskUpdate summary: Update the task, typically to indicate progress, completion, or failure. security: [{ worker_auth: [] }] tags: [worker] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } requestBody: description: Task update information required: true content: application/json: schema: $ref: "#/components/schemas/TaskUpdate" responses: "204": description: The update was accepted. "409": description: The task is assigned to another worker, so the update was not accepted. default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/task/{task_id}/may-i-run: summary: Workers check whether they're allowed to keep running this task. get: operationId: mayWorkerRun summary: > The response indicates whether the worker is allowed to run / keep running the task. Optionally contains a queued worker status change. security: [{ worker_auth: [] }] tags: [worker] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: normal response content: application/json: schema: $ref: "#/components/schemas/MayKeepRunning" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/worker/task/{task_id}/output-produced: summary: Workers send thumbnails/previews of their last-produced output here. post: operationId: taskOutputProduced summary: > Store the most recently rendered frame here. Note that it is up to the Worker to ensure this is in a format that's digestable by the Manager. Currently only PNG and JPEG support is planned. security: [{ worker_auth: [] }] tags: [worker] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } requestBody: description: Contents of the file required: true content: image/jpeg: { schema: { type: string, format: binary } } image/png: { schema: { type: string, format: binary } } responses: "202": description: The file was accepted for processing. "411": description: Length required; the client did not send a Content-Length header. content: application/json: schema: $ref: "#/components/schemas/Error" "413": description: Payload too large. content: application/json: schema: $ref: "#/components/schemas/Error" "415": description: Unsupported Media Type, the image format cannot be processed by the Manager. content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: The client is sending too many frames, and should throttle itself. content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" # Worker Management /api/v3/worker-mgt/workers: summary: Obtain list of Workers known to the Manager. get: operationId: fetchWorkers summary: Get list of workers. tags: [worker-mgt] responses: "200": description: Known workers content: application/json: schema: { $ref: "#/components/schemas/WorkerList" } /api/v3/worker-mgt/workers/{worker_id}: summary: Get detailed worker info. get: operationId: fetchWorker summary: Fetch info about the worker. tags: [worker-mgt] parameters: - name: worker_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: Worker info content: application/json: schema: { $ref: "#/components/schemas/Worker" } /api/v3/worker-mgt/workers/{worker_id}/setstatus: summary: Request a status change for the given worker. post: operationId: requestWorkerStatusChange tags: [worker-mgt] parameters: - name: worker_id in: path required: true schema: { type: string, format: uuid } requestBody: description: The status change to request. required: true content: application/json: schema: $ref: "#/components/schemas/WorkerStatusChangeRequest" responses: "204": description: Status change was accepted. default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" ## Jobs /api/v3/jobs/types: summary: Available Flamenco job types. get: operationId: getJobTypes summary: Get list of job types and their parameters. tags: [jobs] responses: "200": description: Available job types content: application/json: schema: { $ref: "#/components/schemas/AvailableJobTypes" } /api/v3/jobs/type/{typeName}: summary: Info about a specific job type. get: operationId: getJobType summary: Get single job type and its parameters. tags: [jobs] parameters: - name: typeName in: path required: true schema: { type: string } responses: "200": description: Job type content: application/json: schema: { $ref: "#/components/schemas/AvailableJobType" } /api/v3/jobs: summary: Job submission endpoint. post: operationId: submitJob summary: Submit a new job for Flamenco Manager to execute. tags: [jobs] requestBody: description: Job to submit required: true content: application/json: schema: $ref: "#/components/schemas/SubmittedJob" responses: "200": description: Job was succesfully compiled into individual tasks. content: application/json: schema: { $ref: "#/components/schemas/Job" } default: description: Error message content: application/json: schema: { $ref: "#/components/schemas/Error" } /api/v3/jobs/query: summary: Obtain jobs with filtering and sorting. post: operationId: queryJobs summary: Fetch list of jobs. tags: [jobs] requestBody: description: Specification of which jobs to get. required: true content: application/json: schema: $ref: "#/components/schemas/JobsQuery" responses: "200": description: Normal query response, can be empty list if nothing matched the query. content: application/json: schema: { $ref: "#/components/schemas/JobsQueryResult" } default: description: Error message content: application/json: schema: { $ref: "#/components/schemas/Error" } /api/v3/jobs/{job_id}: summary: Job info and management get: operationId: fetchJob summary: Fetch info about the job. tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: Job info content: application/json: schema: { $ref: "#/components/schemas/Job" } /api/v3/jobs/{job_id}/last-rendered: summary: Obtain info about the last-rendered images for this job. get: operationId: fetchJobLastRenderedInfo summary: Get the URL that serves the last-rendered images of this job. tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: Normal response. content: application/json: schema: { $ref: "#/components/schemas/JobLastRenderedImageInfo" } "204": description: This job doesn't have any last-rendered image. /api/v3/jobs/last-rendered: summary: Obtain info about the global last-rendered image. get: operationId: fetchGlobalLastRenderedInfo summary: Get the URL that serves the last-rendered images. tags: [jobs] responses: "200": description: Normal response. content: application/json: schema: { $ref: "#/components/schemas/JobLastRenderedImageInfo" } "204": description: This job doesn't have any last-rendered image. /api/v3/jobs/{job_id}/setstatus: summary: Request a status change for the given job. post: operationId: setJobStatus tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } requestBody: description: The status change to request. required: true content: application/json: schema: $ref: "#/components/schemas/JobStatusChange" responses: "204": description: Status change was accepted. "422": description: The requested status change is not valid for the current status of the job. default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/jobs/{job_id}/tasks: summary: Access tasks of this job. get: operationId: fetchJobTasks summary: Fetch a summary of all tasks of the given job. tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: Get summaries of the tasks of this job. content: application/json: schema: { $ref: "#/components/schemas/JobTasksSummary" } default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/jobs/{job_id}/blocklist: summary: Access blocklist of this job. get: operationId: fetchJobBlocklist summary: Fetch the list of workers that are blocked from doing certain task types on this job. tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: Get tuples (worker, task type) that got blocked on this job. content: application/json: schema: { $ref: "#/components/schemas/JobBlocklist" } default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" delete: operationId: removeJobBlocklist summary: Remove entries from a job blocklist. tags: [jobs] parameters: - name: job_id in: path required: true schema: { type: string, format: uuid } requestBody: description: Tuples (worker, task type) to be removed from the blocklist. content: application/json: schema: { $ref: "#/components/schemas/JobBlocklist" } responses: "204": description: Request accepted, entries have been removed. default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/tasks/{task_id}: summary: Fetch a single task get: operationId: fetchTask summary: Fetch a single task. tags: [jobs] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: The task info. content: application/json: schema: { $ref: "#/components/schemas/Task" } default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/tasks/{task_id}/logtail: summary: Fetch the task's last few log lines. get: operationId: fetchTaskLogTail summary: Fetch the last few lines of the task's log. tags: [jobs] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } responses: "200": description: The task log. content: text/plain: schema: type: string "204": description: Returned when the task has no log yet. default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/tasks/{task_id}/setstatus: summary: > Request a status change for the given task. This may have effect on the job status as well. This endpoint is meant for humans managing tasks via the web interface. Workers post to `/api/v3/worker/task/{task_id}` instead. post: operationId: setTaskStatus tags: [jobs] parameters: - name: task_id in: path required: true schema: { type: string, format: uuid } requestBody: description: The status change to request. required: true content: application/json: schema: $ref: "#/components/schemas/TaskStatusChange" responses: "204": description: Status change was accepted. "422": description: The requested status change is not valid for the current status of the task. default: description: Unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" ## Shaman /api/v3/shaman/checkout/requirements: summary: Allows a client to check which files are available on the server, and which ones are still unknown. post: operationId: shamanCheckoutRequirements summary: Checks a Shaman Requirements file, and reports which files are unknown. tags: [shaman] requestBody: description: Set of files to check required: true content: application/json: schema: $ref: "#/components/schemas/ShamanRequirementsRequest" responses: "200": description: Subset of the posted requirements, indicating the unknown files. content: application/json: schema: $ref: "#/components/schemas/ShamanRequirementsResponse" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/shaman/checkout/create: summary: Symlink a set of files into the checkout area. post: operationId: shamanCheckout summary: Create a directory, and symlink the required files into it. The files must all have been uploaded to Shaman before calling this endpoint. tags: [shaman] requestBody: description: Set of files to check out. required: true content: application/json: schema: $ref: "#/components/schemas/ShamanCheckout" responses: "200": description: Checkout was created succesfully. content: application/json: schema: $ref: "#/components/schemas/ShamanCheckoutResult" "424": description: There were files missing. Use `shamanCheckoutRequirements` to figure out which ones. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: Checkout already exists. content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /api/v3/shaman/files/{checksum}/{filesize}: summary: Upload files to the Shaman server. get: operationId: shamanFileStoreCheck summary: > Check the status of a file on the Shaman server. tags: [shaman] parameters: - name: checksum in: path required: true schema: { type: string } description: SHA256 checksum of the file. - name: filesize in: path required: true schema: { type: integer } description: Size of the file in bytes. responses: "200": description: Normal response. content: application/json: schema: { $ref: "#/components/schemas/ShamanSingleFileStatus" } default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" post: operationId: shamanFileStore summary: > Store a new file on the Shaman server. Note that the Shaman server can forcibly close the HTTP connection when another client finishes uploading the exact same file, to prevent double uploads. The file's contents should be sent in the request body. tags: [shaman] parameters: - name: checksum in: path required: true schema: { type: string } description: SHA256 checksum of the file. - name: filesize in: path required: true schema: { type: integer } description: Size of the file in bytes. - name: X-Shaman-Can-Defer-Upload in: header required: false schema: { type: boolean } description: > The client indicates that it can defer uploading this file. The "208" response will not only be returned when the file is already fully known to the Shaman server, but also when someone else is currently uploading this file. - name: X-Shaman-Original-Filename in: header required: false schema: { type: string } description: > The original filename. If sent along with the request, it will be included in the server logs, which can aid in debugging. requestBody: description: Contents of the file required: true content: application/octet-stream: schema: type: string format: binary responses: "204": description: The file was accepted. "208": description: The file was already known to the server. "417": description: > There was a mismatch between the request parameters and the actual file size or checksum of the uploaded file. "425": description: > Client should defer uploading this file. The file is currently in the process of being uploaded by someone else, and `X-Shaman-Can-Defer-Upload: true` was sent in the request. default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" tags: - name: meta description: Info about the Flamenco Manager itself. - name: jobs description: Job & task queries, submission, and management. - name: worker description: API for Flamenco Workers to communicate with Flamenco Manager. - name: worker-mgt description: Worker Management API, for the web interface to query and control Workers. - name: shaman description: Shaman API, for file uploading & creating job checkouts. components: schemas: FlamencoVersion: type: object required: [version, name] properties: version: { type: string } name: { type: string } ManagerConfiguration: type: object properties: "storageLocation": description: Directory used for job file storage. type: string "shamanEnabled": description: Whether the Shaman file transfer API is available. type: boolean required: [storageLocation, shamanEnabled] WorkerRegistration: type: object required: [secret, platform, supported_task_types, name] properties: secret: { type: string } platform: { type: string } supported_task_types: type: array items: { type: string } name: { type: string } RegisteredWorker: type: object properties: uuid: { type: string, format: uuid } name: { type: string } address: { type: string } status: { $ref: "#/components/schemas/WorkerStatus" } platform: { type: string } software: { type: string } supported_task_types: type: array items: { type: string } required: - uuid - name - address - status - platform - current_task - software - supported_task_types WorkerStatus: type: string enum: [starting, awake, asleep, error, testing, offline] WorkerSignOn: type: object properties: name: { type: string } supported_task_types: type: array items: { type: string } software_version: { type: string } required: [name, supported_task_types, software_version] WorkerStateChange: type: object properties: status_requested: { $ref: "#/components/schemas/WorkerStatus" } required: [status_requested] WorkerStateChanged: type: object properties: status: { $ref: "#/components/schemas/WorkerStatus" } required: [status] AssignedTask: type: object description: AssignedTask is a task as it is received by the Worker. properties: uuid: { type: string, format: uuid } job: { type: string } name: { type: string } status: { $ref: "#/components/schemas/TaskStatus" } priority: { type: integer } job_priority: { type: integer } job_type: { type: string } task_type: { type: string } commands: type: array items: { $ref: "#/components/schemas/Command" } required: - uuid - job - name - status - priority - job_priority - job_type - task_type - commands TaskUpdate: type: object description: > TaskUpdate is sent by a Worker to update the status & logs of a task it's executing. All properties are optional; omitted properties are ignored (i.e. omitting `activity` will not erase the activity property of the task). properties: "taskStatus": $ref: "#/components/schemas/TaskStatus" description: The new task status. "activity": type: string description: One-liner to indicate what's currently happening with the task. Overwrites previously sent activity strings. "log": type: string description: Log lines for this task, will be appended to logs sent earlier. MayKeepRunning: type: object description: Indicates whether the worker may keep running the task. properties: "mayKeepRunning": { type: boolean } "reason": { type: string } "statusChangeRequested": type: boolean description: > Indicates that a status change requested for the worker. It should use the `workerState` operation to determine which state to go to next. If this is `true`, `mayKeepRunning` MUST be `false`. required: ["mayKeepRunning", "reason", "statusChangeRequested"] JobStatus: type: string enum: - active - canceled - completed - construction-failed - failed - paused - queued - archived - archiving - cancel-requested - requeueing - under-construction TaskStatus: type: string enum: - active - canceled - completed - failed - queued - soft-failed - paused Command: type: object description: Command represents a single command to execute by the Worker. properties: name: { type: string } parameters: { type: object } required: [name, parameters] AvailableJobTypes: type: object description: List of job types supported by this Manager. properties: "job_types": type: array items: { $ref: "#/components/schemas/AvailableJobType" } required: [job_types] AvailableJobType: type: object description: Job type supported by this Manager, and its parameters. properties: "name": { type: string } "label": { type: string } "settings": type: array items: { $ref: "#/components/schemas/AvailableJobSetting" } required: [name, label, settings] AvailableJobSetting: type: object description: Single setting of a Job types. properties: "key": type: string description: Identifier for the setting, must be unique within the job type. "type": { $ref: "#/components/schemas/AvailableJobSettingType" } "subtype": { $ref: "#/components/schemas/AvailableJobSettingSubtype" } "choices": description: When given, limit the valid values to these choices. Only usable with string type. type: array items: { type: string } "propargs": description: Any extra arguments to the bpy.props.SomeProperty() call used to create this property. type: object "description": description: The description/tooltip shown in the user interface. "default": description: The default value shown to the user when determining this setting. "eval": type: string description: Python expression to be evaluated in order to determine the default value for this setting. "visible": $ref: "#/components/schemas/AvailableJobSettingVisibility" "required": type: boolean description: > Whether to immediately reject a job definition, of this type, without this particular setting. default: false "editable": type: boolean description: > Whether to allow editing this setting after the job has been submitted. Would imply deleting all existing tasks for this job, and recompiling it. default: false required: [key, type] AvailableJobSettingType: type: string description: > Type of job setting, must be usable as IDProperty type in Blender. No nested structures (arrays, dictionaries) are supported. enum: [string, int32, float, bool] AvailableJobSettingSubtype: type: string description: > Sub-type of the job setting. Currently only available for string types. `HASHED_FILE_PATH` is a directory path + `"/######"` appended. enum: ["file_path", "dir_path", "file_name", "hashed_file_path"] AvailableJobSettingVisibility: type: string description: > When to show this setting. `visible`: always show. `submission`: only show in the UI of a job submitter (like a Blender add-on). `web`: only show in the web interface for management, but not when submitting the job. `hidden`: never show; only available to the job compiler script as internal setting. enum: [visible, hidden, submission, web] default: visible SubmittedJob: type: object description: Job definition submitted to Flamenco. properties: "name": { type: string } "type": { type: string } "priority": { type: integer, default: 50 } "settings": { $ref: "#/components/schemas/JobSettings" } "metadata": { $ref: "#/components/schemas/JobMetadata" } required: [name, type, priority] example: type: "simple-blender-render" name: 3Д рендеринг priority: 50 settings: blender_cmd: "{blender}" filepath: "/render/sf/jobs/scene123.blend" render_output_root: "/render/sf/frames/scene123" render_output_path: "/render/sf/frames/scene123/3Д рендеринг/######" frames: "1-10" chunk_size: 3 fps: 24 extract_audio: true images_or_video: "images" format: "PNG" output_file_extension: ".png" metadata: "user.name": "Sybren Stüvel" "user.email": "sybren@blender.org" "project": "Sprite Fright" Job: allOf: - $ref: "#/components/schemas/SubmittedJob" - properties: id: type: string format: uuid description: UUID of the Job created: type: string format: date-time description: Creation timestamp updated: type: string format: date-time description: Timestamp of last update. status: { $ref: "#/components/schemas/JobStatus" } activity: type: string description: Description of the last activity on this job. required: [id, created, updated, status, activity] JobSettings: type: object additionalProperties: true JobMetadata: type: object description: Arbitrary metadata strings. More complex structures can be modeled by using `a.b.c` notation for the key. additionalProperties: type: string example: "user.name": Sybren Stüvel "user.email": sybren@blender.org "project": "Sprite Fright" JobsQuery: type: object properties: "offset": type: integer minimum: 0 "limit": type: integer minimum: 1 "order_by": type: array items: { type: string } "status_in": type: array items: { $ref: "#/components/schemas/JobStatus" } description: Return only jobs with a status in this array. "metadata": type: object additionalProperties: type: string description: Filter by metadata, using `LIKE` notation. "settings": type: object additionalProperties: true description: Filter by job settings, using `LIKE` notation. example: "limit": 5 "order_by": ["updated", "status"] "status_in": ["active", "queued", "failed"] "metadata": { project: "Sprite Fright" } JobsQueryResult: type: object properties: jobs: type: array items: { $ref: "#/components/schemas/Job" } required: [jobs] Task: type: object description: The task as it exists in the Manager database, i.e. before variable replacement. properties: "id": { type: string, format: uuid } "created": type: string format: date-time description: Creation timestamp "updated": type: string format: date-time description: Timestamp of last update. "job_id": { type: string, format: uuid } "name": { type: string } "status": { $ref: "#/components/schemas/TaskStatus" } "priority": { type: integer } "task_type": { type: string } "activity": { type: string } "commands": type: array items: { $ref: "#/components/schemas/Command" } "worker": { $ref: "#/components/schemas/TaskWorker" } "last_touched": type: string format: date-time description: Timestamp of when any worker worked on this task. "failed_by_workers": type: array items: { $ref: "#/components/schemas/TaskWorker" } required: - id - created - updated - job_id - name - status - priority - task_type - activity - commands TaskWorker: type: object description: Worker reference, as used in Task objects. properties: "id": { type: string, format: uuid } "name": { type: string } "address": { type: string } required: [id, name, address] JobTasksSummary: description: "Simplified list of tasks of a job. Contains all tasks, but not all info of each task." type: object properties: tasks: type: array items: { $ref: "#/components/schemas/TaskSummary" } required: [jobs] TaskSummary: type: object description: Just enough information about the task to show in the job's task list. properties: id: { type: string, format: uuid } name: { type: string } status: { $ref: "#/components/schemas/TaskStatus" } priority: { type: integer } task_type: { type: string } updated: { type: string, format: date-time } required: [id, name, status, priority, task_type, updated] JobLastRenderedImageInfo: description: > Enough information for a client to piece together different strings to form a host-relative URL to the last-rendered image. To construct the URL, concatenate "{base}/{one of the suffixes}". type: object properties: "base": { type: string, format: url } "suffixes": type: array items: { type: string } required: [base, suffixes] JobBlocklist: description: "List of workers that are not allowed certain task types on a specific job." type: array items: { $ref: "#/components/schemas/JobBlocklistEntry" } JobBlocklistEntry: type: object properties: worker_id: { type: string, format: uuid } task_type: { type: string } required: [worker_id, task_type] JobStatusChange: type: object properties: status: { $ref: "#/components/schemas/JobStatus" } reason: type: string description: The reason for this status change. required: [status, reason] TaskStatusChange: type: object properties: status: { $ref: "#/components/schemas/TaskStatus" } reason: type: string description: The reason for this status change. required: [status, reason] Error: description: Generic error response. type: object required: [code, message] properties: code: type: integer format: int32 description: > HTTP status code of this response. Is included in the payload so that a single object represents all error information. Code 503 is used when the database is busy. The HTTP response will contain a 'Retry-After' HTTP header that indicates after which time the request can be retried. Following the header is not mandatory, and it's up to the client to do something reasonable like exponential backoff. message: { type: string } SecurityError: type: object required: [message] properties: message: { type: string } ShamanRequirementsRequest: type: object description: Set of files with their SHA256 checksum and size in bytes. properties: "files": type: array items: { $ref: "#/components/schemas/ShamanFileSpec" } required: [files] example: files: - sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0 size: 1424 - sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079 size: 127 ShamanRequirementsResponse: type: object description: The files from a requirements request, with their status on the Shaman server. Files that are known to Shaman are excluded from the response. properties: "files": type: array items: { $ref: "#/components/schemas/ShamanFileSpecWithStatus" } required: [files] example: files: - sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0 size: 1424 status: unknown - sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079 size: 127 status: uploading ShamanFileSpec: type: object description: Specification of a file in the Shaman storage. properties: "sha": { type: string, description: "SHA256 checksum of the file" } "size": { type: integer, description: "File size in bytes" } "path": type: string description: "Location of the file in the checkout" required: [sha, size, path] ShamanFileSpecWithStatus: # Using allOf here would trigger a bug in the Python code generator, # resulting in this error: # # Values stored for property status in ShamanFileSpecWithStatus differ # when looking at self and self's composed instances. All values must be # the same at ['['received_data', 'files', 0]']['status'] # # The underlying cause is that composited types can apparently store # property values multiple times, and these have to be equal. However, one # is using the `ShamanFileStatus` type, and the other is using the `str` # type to store the same status value. # # To work around this, even though this should be a composition of # `ShamanFileSpec` with some extra properties, we just repeat those same # properties here. type: object description: Specification of a file, which could be in the Shaman storage, or not, depending on its status. properties: "sha": { type: string, description: "SHA256 checksum of the file" } "size": { type: integer, description: "File size in bytes" } "path": type: string description: "Location of the file in the checkout" "status": { $ref: "#/components/schemas/ShamanFileStatus" } required: [sha, size, path, status] ShamanCheckout: type: object description: Set of files with their SHA256 checksum, size in bytes, and desired location in the checkout directory. properties: "files": type: array items: { $ref: "#/components/schemas/ShamanFileSpec" } "checkoutPath": type: string description: > Path where the Manager should create this checkout. It is relative to the Shaman checkout path as configured on the Manager. In older versions of the Shaman this was just the "checkout ID", but in this version it can be a path like `project-slug/scene-name/unique-ID`. required: [files, checkoutPath] example: files: - sha: 35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0 size: 1424 path: definition.go - sha: 63b72c63b9424fd13b9370fb60069080c3a15717cf3ad442635b187c6a895079 size: 127 path: logging.go ShamanCheckoutResult: type: object description: The result of a Shaman checkout. properties: "checkoutPath": type: string description: > Path where the Manager created this checkout. This can be different than what was requested, as the Manager will ensure a unique directory. The path is relative to the Shaman checkout path as configured on the Manager. required: [checkoutPath] ShamanFileStatus: type: string enum: [unknown, uploading, stored] ShamanSingleFileStatus: type: object description: Status of a file in the Shaman storage. properties: "status": { $ref: "#/components/schemas/ShamanFileStatus" } required: [status] # SocketIO API. These types are not used in any HTTP operation defined in # the 'paths' section of this document, so some code generators may choose # to skip these. SocketIOJobUpdate: type: object description: > Subset of a Job, sent over SocketIO when a job changes. For new jobs, `previous_status` will be excluded. properties: "id": type: string format: uuid description: UUID of the Job "name": { type: string, description: "Name of the job" } "updated": type: string format: date-time description: Timestamp of last update "status": { $ref: "#/components/schemas/JobStatus" } "previous_status": { $ref: "#/components/schemas/JobStatus" } "type": { type: string } "priority": { type: integer, default: 50 } "refresh_tasks": type: boolean description: > Indicates that the client should refresh all the job's tasks. This is sent for mass updates, where updating each individual task would generate too many updates to be practical. required: [id, updated, status, type, priority, refresh_tasks] SocketIOTaskUpdate: type: object description: > Subset of a Task, sent over SocketIO when a task changes. For new tasks, `previous_status` will be excluded. properties: "id": type: string format: uuid description: UUID of the Task "job_id": { type: string, format: uuid } "name": { type: string, description: "Name of the task" } "updated": type: string format: date-time description: Timestamp of last update "status": { $ref: "#/components/schemas/TaskStatus" } "previous_status": { $ref: "#/components/schemas/TaskStatus" } "activity": { type: string } required: [id, job_id, name, updated, status, activity] SocketIOTaskLogUpdate: type: object description: > Task log chunk, sent to a SocketIO room dedicated to a single task, to avoid sending too many updates. properties: "task_id": type: string format: uuid description: UUID of the Task "log": type: string description: Chunk of the task log. May contain multiple lines of text. required: [task_id, log] SocketIOLastRenderedUpdate: type: object description: Indicator that the last-rendered image of this job was updated. properties: "job_id": { type: string, format: uuid } "thumbnail": { $ref: "#/components/schemas/JobLastRenderedImageInfo" } required: [job_id, task_id, thumbnail] SocketIOWorkerUpdate: type: object description: > Subset of a Worker, sent over SocketIO when a worker changes. properties: "id": type: string format: uuid description: UUID of the Worker "name": { type: string, description: "Name of the worker" } "updated": type: string format: date-time description: Timestamp of last update "status": { $ref: "#/components/schemas/WorkerStatus" } "previous_status": { $ref: "#/components/schemas/WorkerStatus" } "status_change": $ref: "#/components/schemas/WorkerStatusChangeRequest" "version": { type: string } required: [id, name, updated, status, version] SocketIOSubscription: type: object description: > Send by SocketIO clients as `/subscription` event type, to manage their subscription to job updates. Clients always get job updates, but for task updates or task logs they need to explicitly subscribe. For simplicity, clients can only subscribe to one job (to get task updates for that job) and one task's log at a time. properties: "op": { $ref: "#/components/schemas/SocketIOSubscriptionOperation" } "type": { $ref: "#/components/schemas/SocketIOSubscriptionType" } "uuid": type: string format: uuid description: UUID of the thing to subscribe to / unsubscribe from. required: [op, type] SocketIOSubscriptionOperation: type: string enum: [subscribe, unsubscribe] SocketIOSubscriptionType: type: string enum: [allJobs, allWorkers, job, tasklog, allLastRendered] description: What kind of thing to subscribe to / unsubscribe from. # Worker Management WorkerList: type: object description: List of workers. properties: "workers": type: array items: { $ref: "#/components/schemas/WorkerSummary" } required: [workers] WorkerSummary: type: object description: Basic information about a Worker. properties: "id": { type: string, format: uuid } "name": { type: string } "status": { $ref: "#/components/schemas/WorkerStatus" } "status_change": $ref: "#/components/schemas/WorkerStatusChangeRequest" # These will be implemented soon: # "task_id": # type: string # format: uuid # description: The worker's current/last-worked-on task. # "last_seen": # type: string # format: date-time # description: Last time this worker was seen by the Manager. "version": type: string description: Version of Flamenco this Worker is running required: [id, name, status, version] Worker: description: All information about a Worker allOf: - $ref: "#/components/schemas/WorkerSummary" - properties: "ip_address": type: string description: IP address of the Worker "platform": type: string description: Operating system of the Worker "supported_task_types": type: array items: { type: string } required: - id - name - status - ip_address - platform - version - supported_task_types WorkerStatusChangeRequest: type: object description: Request for a Worker to change its status to `status`. properties: "status": { $ref: "#/components/schemas/WorkerStatus" } "is_lazy": type: boolean description: > Whether the status change should happen immediately, or after the worker's current task is finished. required: [status, is_lazy] securitySchemes: worker_auth: description: Username is the worker ID, password is the secret given at worker registration. type: http scheme: basic