Expanso Orchestrator API

openapi: 3.2.0
info:
  description: This page is the reference of the Bacalhau REST API. Project docs are available at https://docs.bacalhau.org/. Find more information about Bacalhau at https://github.com/bacalhau-project/bacalhau.
  title: Bacalhau Ops Orchestrator API
  contact:
    name: Bacalhau Team
    url: https://github.com/bacalhau-project/bacalhau
    email: team@bacalhau.org
  license:
    name: Apache 2.0
    url: https://github.com/bacalhau-project/bacalhau/blob/main/LICENSE
servers:
- url: http://localhost:1234/
tags:
- name: Orchestrator
paths:
  /api/v1/orchestrator/jobs:
    get:
      description: Returns a list of jobs.
      tags:
      - Orchestrator
      summary: Returns a list of jobs.
      operationId: orchestrator/listJobs
      parameters:
      - description: Namespace to get the jobs for
        name: namespace
        in: query
        schema:
          type: string
      - description: Limit the number of jobs returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Token to get the next page of jobs
        name: next_token
        in: query
        schema:
          type: string
      - description: Reverse the order of the jobs
        name: reverse
        in: query
        schema:
          type: boolean
      - description: Order the jobs by the given field
        name: order_by
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListJobsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
    put:
      description: Submits a job to the orchestrator.
      tags:
      - Orchestrator
      summary: Submits a job to the orchestrator.
      operationId: orchestrator/putJob
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.PutJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apimodels.PutJobRequest'
        description: Job to submit
        required: true
  /api/v1/orchestrator/jobs/diff:
    put:
      description: Compares a submitted job spec with the existing job that has the same name, and returns the differences between them.
      tags:
      - Orchestrator
      summary: Compares a job spec with an existing job of the same name.
      operationId: orchestrator/diffJob
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.DiffJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apimodels.DiffJobRequest'
        description: Job spec to compare with existing job
        required: true
  /api/v1/orchestrator/jobs/{id}:
    get:
      description: Returns a job.
      tags:
      - Orchestrator
      summary: Returns a job.
      operationId: orchestrator/getJob
      parameters:
      - description: ID to get the job for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: history and executions options. Empty includes nothing
        name: include
        in: query
        schema:
          type: string
      - description: Number of items to fetch. Use with include parameter
        name: limit
        in: query
        schema:
          type: integer
      - description: Job version to get. Defaults to 0.
        name: job_version
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.GetJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
    delete:
      description: Stops a job.
      tags:
      - Orchestrator
      summary: Stops a job.
      operationId: orchestrator/stopJob
      parameters:
      - description: ID to stop the job for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Reason for stopping the job
        name: reason
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.StopJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/jobs/{id}/executions:
    get:
      description: Returns the executions of a job.
      tags:
      - Orchestrator
      summary: Returns the executions of a job.
      operationId: orchestrator/jobExecutions
      parameters:
      - description: ID to get the job executions for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Namespace to get the jobs for
        name: namespace
        in: query
        schema:
          type: string
      - description: Limit the number of executions returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Token to get the next page of executions
        name: next_token
        in: query
        schema:
          type: string
      - description: Reverse the order of the executions
        name: reverse
        in: query
        schema:
          type: boolean
      - description: Order the executions by the given field
        name: order_by
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListJobExecutionsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/jobs/{id}/history:
    get:
      description: Returns the history of a job.
      tags:
      - Orchestrator
      summary: Returns the history of a job.
      operationId: orchestrator/listHistory
      parameters:
      - description: ID to get the job history for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Limit the number of history events returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Only return history since this time
        name: since
        in: query
        schema:
          type: string
      - description: Only return history of this event type
        name: event_type
        in: query
        schema:
          type: string
      - description: Only return history of this execution ID
        name: execution_id
        in: query
        schema:
          type: string
      - description: Token to get the next page of the history events
        name: next_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListJobHistoryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/jobs/{id}/logs:
    get:
      description: 'Establishes a WebSocket connection to stream output from the job specified by `id`

        The stream will continue until either the client disconnects or the execution completes'
      tags:
      - Orchestrator
      summary: Streams the logs for a current job/execution via WebSocket
      operationId: orchestrator/logs
      parameters:
      - description: ID of the job to stream logs for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Fetch logs for a specific execution
        name: execution_id
        in: query
        schema:
          type: string
      - description: Fetch historical logs
        name: tail
        in: query
        schema:
          type: boolean
      - description: Follow the logs
        name: follow
        in: query
        schema:
          type: boolean
      responses:
        '101':
          description: Switching Protocols to WebSocket
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/models.ExecutionLog'
        '400':
          description: Bad Request
          content:
            application/octet-stream:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/octet-stream:
              schema:
                type: string
  /api/v1/orchestrator/jobs/{id}/rerun:
    put:
      description: Reruns a job with the specified job ID or name.
      tags:
      - Orchestrator
      summary: Reruns a job.
      operationId: orchestrator/rerunJob
      parameters:
      - description: ID or name of the job to rerun
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.RerunJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apimodels.RerunJobRequest'
        description: Request to rerun job
        required: true
  /api/v1/orchestrator/jobs/{id}/results:
    get:
      description: Returns the results of a job.
      tags:
      - Orchestrator
      summary: Returns the results of a job.
      operationId: orchestrator/jobResults
      parameters:
      - description: ID to get the job results for
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListJobResultsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/jobs/{id}/versions:
    get:
      description: Returns the versions of a job.
      tags:
      - Orchestrator
      summary: Returns the versions of a job.
      operationId: orchestrator/jobVersions
      parameters:
      - description: ID or Name to get the job versions for
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Namespace of the job
        name: namespace
        in: query
        schema:
          type: string
      - description: Limit the number of job versions returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Token to get the next page of job versions
        name: next_token
        in: query
        schema:
          type: string
      - description: Reverse the order of the job versions
        name: reverse
        in: query
        schema:
          type: boolean
      - description: Order the job versions by the given field
        name: order_by
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListJobVersionsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/nodes:
    get:
      description: Returns a list of orchestrator nodes.
      tags:
      - Orchestrator
      summary: Returns a list of orchestrator nodes.
      operationId: orchestrator/listNodes
      parameters:
      - description: Limit the number of node returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Token to get the next page of nodes
        name: next_token
        in: query
        schema:
          type: string
      - description: Reverse the order of the nodes
        name: reverse
        in: query
        schema:
          type: boolean
      - description: Order the nodes by given field
        name: order_by
        in: query
        schema:
          type: string
      - description: Filter Approval
        name: filter_approval
        in: query
        schema:
          type: string
      - description: Filter Status
        name: filter-status
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.ListNodesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/orchestrator/nodes/{id}:
    get:
      description: Get an orchestrator node
      tags:
      - Orchestrator
      summary: Get an orchestrator node
      operationId: orchestrator/getNode
      parameters:
      - description: ID of the orchestrator node to fetch for.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.GetNodeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
    put:
      description: Update an orchestrator node.
      tags:
      - Orchestrator
      summary: Update an orchestrator node.
      operationId: orchestrator/updateNode
      parameters:
      - description: ID of the orchestrator node.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apimodels.PutNodeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apimodels.PutNodeRequest'
        description: Put Node Request
        required: true
components:
  schemas:
    models.RunCommandResult:
      type: object
      properties:
        ErrorMsg:
          description: Runner error
          type: string
        ExitCode:
          description: exit code of the run.
          type: integer
        StderrTruncated:
          description: bool describing if stderr was truncated
          type: boolean
        Stdout:
          description: stdout of the run. Yaml provided for `describe` output
          type: string
        StdoutTruncated:
          description: bool describing if stdout was truncated
          type: boolean
        stderr:
          description: stderr of the run.
          type: string
    models.State-models_ExecutionStateType:
      type: object
      properties:
        Details:
          description: Details is a map of additional details about the state.
          type: object
          additionalProperties:
            type: string
        Message:
          description: Message is a human readable message describing the state.
          type: string
        StateType:
          description: StateType is the current state of the object.
          allOf:
          - $ref: '#/components/schemas/models.ExecutionStateType'
    apimodels.GetNodeResponse:
      type: object
      properties:
        Node:
          $ref: '#/components/schemas/models.NodeState'
    models.ConnectionState:
      type: object
      properties:
        ConnectedSince:
          description: Connection tracking
          type: string
        DisconnectedSince:
          type: string
        LastComputeSeqNum:
          description: Message sequencing for reliable delivery
          type: integer
        LastError:
          type: string
        LastHeartbeat:
          description: Last successful heartbeat timestamp
          type: string
        LastOrchestratorSeqNum:
          description: Last seq received from orchestrator
          type: integer
        Status:
          description: Connection status
          allOf:
          - $ref: '#/components/schemas/models.NodeConnectionState'
    models.ExecutionStateType:
      type: integer
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      x-enum-comments:
        ExecutionStateBidAccepted: aka running
      x-enum-descriptions:
      - ''
      - ''
      - ''
      - ''
      - ''
      - aka running
      - ''
      - ''
      - ''
      - ''
      - ''
      - ''
      x-enum-varnames:
      - ExecutionStateUndefined
      - ExecutionStateNew
      - ExecutionStateAskForBid
      - ExecutionStateAskForBidAccepted
      - ExecutionStateAskForBidRejected
      - ExecutionStateBidAccepted
      - ExecutionStateRunning
      - ExecutionStatePublishing
      - ExecutionStateBidRejected
      - ExecutionStateCompleted
      - ExecutionStateFailed
      - ExecutionStateCancelled
    models.LabelSelectorRequirement:
      type: object
      properties:
        Key:
          description: key is the label key that the selector applies to.
          type: string
        Operator:
          description: 'operator represents a key''s relationship to a set of values.

            Valid operators are In, NotIn, Exists and KeyNotInImap.'
          allOf:
          - $ref: '#/components/schemas/selection.Operator'
        Values:
          description: 'values is an array of string values. If the operator is In or NotIn,

            the values array must be non-empty. If the operator is Exists or KeyNotInImap,

            the values array must be empty. This array is replaced during a strategic'
          type: array
          items:
            type: string
    models.Protocol:
      type: string
      enum:
      - ncl/v1
      - bprotocol/v2
      x-enum-varnames:
      - ProtocolNCLV1
      - ProtocolBProtocolV2
    models.State-models_JobStateType:
      type: object
      properties:
        Details:
          description: Details is a map of additional details about the state.
          type: object
          additionalProperties:
            type: string
        Message:
          description: Message is a human readable message describing the state.
          type: string
        StateType:
          description: StateType is the current state of the object.
          allOf:
          - $ref: '#/components/schemas/models.JobStateType'
    models.NetworkConfig:
      type: object
      properties:
        Domains:
          type: array
          items:
            type: string
        Ports:
          type: array
          items:
            $ref: '#/components/schemas/models.Port'
        Type:
          $ref: '#/components/schemas/models.Network'
    models.NodeType:
      type: integer
      enum:
      - 0
      - 1
      - 2
      x-enum-varnames:
      - nodeTypeUndefined
      - NodeTypeRequester
      - NodeTypeCompute
    apimodels.PutJobRequest:
      type: object
      properties:
        Force:
          type: boolean
        Job:
          $ref: '#/components/schemas/models.Job'
        credential:
          $ref: '#/components/schemas/apimodels.HTTPCredential'
        idempotencyToken:
          type: string
        namespace:
          type: string
    apimodels.StopJobResponse:
      type: object
      properties:
        EvaluationID:
          type: string
    apimodels.ListJobVersionsResponse:
      type: object
      properties:
        Items:
          type: array
          items:
            $ref: '#/components/schemas/models.Job'
        NextToken:
          type: string
    apimodels.RerunJobResponse:
      type: object
      properties:
        EvaluationID:
          type: string
        JobID:
          type: string
        JobVersion:
          type: integer
        Warnings:
          type: array
          items:
            type: string
    selection.Operator:
      type: string
      enum:
      - '!'
      - '='
      - ==
      - in
      - '!='
      - notin
      - exists
      - gt
      - lt
      x-enum-varnames:
      - DoesNotExist
      - Equals
      - DoubleEquals
      - In
      - NotEquals
      - NotIn
      - Exists
      - GreaterThan
      - LessThan
    models.SpecConfig:
      type: object
      properties:
        Params:
          description: Params is a map of the config params
          type: object
          additionalProperties: true
        Type:
          description: Type of the config
          type: string
    models.GPUVendor:
      type: string
      enum:
      - NVIDIA
      - AMD/ATI
      - Intel
      x-enum-varnames:
      - GPUVendorNvidia
      - GPUVendorAMDATI
      - GPUVendorIntel
    models.StateChange-models_JobStateType:
      type: object
      properties:
        New:
          $ref: '#/components/schemas/models.JobStateType'
        Previous:
          $ref: '#/components/schemas/models.JobStateType'
    models.Port:
      type: object
      properties:
        HostNetwork:
          description: 'HostNetwork specifies which network interface to bind to.

            If empty, defaults to "0.0.0.0" (all interfaces).

            Can be set to "127.0.0.1" to only allow local connections.'
          type: string
        Name:
          description: 'Name is a required identifier for this port mapping.

            It will be used to create environment variables to inform the task

            about its allocated ports.'
          type: string
        Static:
          description: 'Static is the host port to use. If not specified, a port will be

            auto-allocated from the compute node''s port range'
          type: integer
        Target:
          description: 'Target is the port inside the task/container that should be exposed.

            Only valid for Bridge network mode. If not specified in Bridge mode,

            it will default to the same value as the host port.'
          type: integer
    models.State-models_ExecutionDesiredStateType:
      type: object
      properties:
        Details:
          description: Details is a map of additional details about the state.
          type: object
          additionalProperties:
            type: string
        Message:
          description: Message is a human readable message describing the state.
          type: string
        StateType:
          description: StateType is the current state of the object.
          allOf:
          - $ref: '#/components/schemas/models.ExecutionDesiredStateType'
    models.TimeoutConfig:
      type: object
      properties:
        ExecutionTimeout:
          description: 'ExecutionTimeout is the maximum amount of time a task is allowed to run in seconds.

            Zero means no timeout, such as for a daemon task.'
          type: integer
        QueueTimeout:
          description: 'QueueTimeout is the maximum amount of time a task is allowed to wait in the orchestrator

            queue in seconds before being scheduled. Zero means no timeout.'
          type: integer
        TotalTimeout:
          description: 'TotalTimeout is the maximum amount of time a task is allowed to complete in seconds.

            This includes the time spent in the queue, the time spent executing and the time spent retrying.

            Zero means no timeout.'
          type: integer
    models.JobStateType:
      type: integer
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      x-enum-varnames:
      - JobStateTypeUndefined
      - JobStateTypePending
      - JobStateTypeQueued
      - JobStateTypeRunning
      - JobStateTypeCompleted
      - JobStateTypeFailed
      - JobStateTypeStopped
    apimodels.PutJobResponse:
      type: object
      properties:
        EvaluationID:
          type: string
        JobID:
          type: string
        Warnings:
          type: array
          items:
            type: string
    apimodels.DiffJobRequest:
      type: object
      properties:
        Job:
          $ref: '#/components/schemas/models.Job'
        credential:
          $ref: '#/components/schemas/apimodels.HTTPCredential'
        idempotencyToken:
          type: string
        namespace:
          type: string
    models.ResourcesConfig:
      type: object
      properties:
        CPU:
          description: CPU https://github.com/BTBurke/k8sresource string
          type: string
        Disk:
          description: Memory github.com/dustin/go-humanize string
          type: string
        GPU:
          type: string
        Memory:
          description: Memory github.com/dustin/go-humanize string
          type: string
    apimodels.PutNodeResponse:
      type: object
      properties:
        Error:
          type: string
        Success:
          type: boolean
    models.JobHistory:
      type: object
      properties:
        Event:
          $ref: '#/components/schemas/models.Event'
        ExecutionID:
          type: string
        ExecutionState:
          description: 'Deprecated: Left for backward compatibility with v1.4.x clients'
          allOf:
          - $ref: '#/components/schemas/models.StateChange-models_ExecutionStateType'
        JobID:
          type: string
        JobState:
          description: 'TODO: remove with v1.5

            Deprecated: Left for backward compatibility with v1.4.x clients'
          allOf:
          - $ref: '#/components/schemas/models.StateChange-models_JobStateType'
        JobVersion:
          type: integer
        SeqNum:
          type: integer
        Time:
          type: string
        Type:
          $ref: '#/components/schemas/models.JobHistoryType'
    models.Job:
      type: object
      properties:
        Constraints:
          description: Constraints is a selector which must be true for the compute node to run this job.
          type: array
          items:
            $ref: '#/components/schemas/models.LabelSelectorRequirement'
        Count:
          description: 'Count is the number of replicas that should be scheduled.

            For batch and service jobs:

            - If not present in JSON, defaults to 1

            - If explicitly set to 0, means stop all executions

            - If > 0, specifies exact number of replicas

            For daemon and ops jobs:

            - Values of 0 or 1 are ignored (job runs on all matching nodes)

            - Values > 1 are invalid and will cause validation to fail'
          type: integer
        CreateTime:
          type: integer
        ID:
          description: 'ID is a unique identifier assigned to this job.

            It helps to distinguish jobs with the same name after they have been deleted and re-created.

            The ID is generated by the server and should not be set directly by the client.'
          type: string
        Labels:
          description: 'Labels is used to associate arbitrary labels with this job, which can be used

            for filtering.

            key=value'
          type: object
          additionalProperties:
            type: string
        Meta:
          description: Meta is used to associate arbitrary metadata with this job.
          type: object
          additionalProperties:
            type: string
        ModifyTime:
          type: integer
        Name:
          description: 'Name is the logical name of the job used to refer to it.

            Submitting a job with the same name as an existing job will result in an

            update to the existing job.'
          type: string
        Namespace:
          description: Namespace is the namespace this job is running in.
          type: string
        Priority:
          description: Priority defines the scheduling priority of this job.
          type: integer
        Revision:
          description: 'Revision is a per-job monotonically increasing revision number that is incremented

            on each update to the job''s state or specification'
          type: integer
        State:
          description: State is the current state of the job.
          allOf:
          - $ref: '#/components/schemas/models.State-models_JobStateType'
        Tasks:
          type: array
          items:
            $ref: '#/components/schemas/models.Task'
        Type:
          description: Type is the type of job this is, e.g. "daemon" or "batch".
          type: string
        Version:
          description: 'Version is a per-job monotonicall

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/expanso/refs/heads/main/openapi/expanso-orchestrator-api-openapi.yml