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:
  /api/version:
    summary: Workers 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/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/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/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/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/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/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/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/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/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/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"}

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.

components:
  schemas:
    FlamencoVersion:
      type: object
      required: [version, name]
      properties:
        version: { type: string }
        name: { type: string }

    WorkerRegistration:
      type: object
      required: [secret, platform, supported_task_types, nickname]
      properties:
        secret: {type: string}
        platform: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
        nickname: {type: string}

    RegisteredWorker:
      type: object
      properties:
        uuid: {type: string, format: uuid}
        nickname: {type: string}
        address: {type: string}
        status: {$ref: "#/components/schemas/WorkerStatus"}
        platform: {type: string}
        last_activity: {type: string}
        software: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
      required: [uuid, nickname, address, status, platform, current_task, last_activity, software, supported_task_types]

    WorkerStatus:
      type: string
      enum: [starting, awake, asleep, error, shutdown, testing, offline]

    WorkerSignOn:
      type: object
      properties:
        nickname: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
        software_version: {type: string}
      required: [nickname, 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.
      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."}

    JobStatus:
      type: string
      enum: [active, canceled, completed, construction-failed, failed, paused, queued, archived, archiving, cancel-requested, fail-requested, requeued, under-construction, waiting-for-files]

    TaskStatus:
      type: string
      enum: [active, canceled, completed, failed, queued, soft-failed, cancel-requested, 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":
          type: boolean
          description: >
            Whether to show this setting in the UI of a job submitter (like a
            Blender add-on). Set to `false` when it is an internal setting that
            shouldn't be shown to end users.
          default: true
        "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"]

    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: "/render/sf/frames/scene123"
          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: Creation timestamp
            status: {$ref: "#/components/schemas/JobStatus"}
          required: [id, created, updated, status]

    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"

    Error:
      type: object
      required: [code, message]
      properties:
        code: {type: integer, format: int32}
        message: {type: string}

    SecurityError:
      type: object
      required: [message]
      properties:
        message: {type: string}

  securitySchemes:
    worker_auth:
      description: Username is the worker ID, password is the secret given at worker registration.
      type: http
      scheme: basic