flamenco/pkg/api/flamenco-manager.yaml

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/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/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"}

  /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"}


tags:
  - name: worker
    description: API for Flamenco Workers to communicate with Flamenco Manager.

components:
  schemas:
    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:
        _id: {type: string}
        nickname: {type: string}
        address: {type: string}
        status: {type: string}
        platform: {type: string}
        last_activity: {type: string}
        software: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
      required: [_id, nickname, address, status, platform, current_task, last_activity, software, supported_task_types]

    AssignedTask:
      type: object
      description: AssignedTask is a task as it is received by the Worker.
      properties:
        _id: {type: string}
        job: {type: string}
        user: {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: [_id, job, user, name, status, priority, job_priority, job_type, task_type, commands]

    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, fail-requested, paused, processing]

    Command:
      type: object
      description: Command represents a single command to execute by the Worker.
      properties:
        name: {type: string}
        settings: {type: object}
      required: [name, settings]

    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}
        "settings":
          type: array
          items: {$ref: "#/components/schemas/AvailableJobSetting"}
      required: [name, 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"}
        "choices":
          description: When given, limit the valid values to these choices. Only usable with string type.
          type: array
          items: {type: string}
        "default":
          description: The default value shown to the user when determining 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
      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]

    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
    user_auth:
      description: >
        OAuth2 authentication flow for authenticating users. Currently not
        implemented, so now more used as a "todo" than actual authentication.
      type: http
      scheme: basic