Expanso
Bacalhau Orchestrator API

The Bacalhau Orchestrator REST API for submitting and managing distributed compute jobs - put/get/stop/rerun jobs, list executions, history, results, versions, and stream job logs, plus orchestrator node management and agent introspection (version, config, node info, auth config). Bacalhau is the open-source engine behind Expanso Cloud.
Documentation GitHub OpenAPI
OpenAPI Specification

{
    "schemes": [
        "http"
    ],
    "swagger": "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 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"
        }
    },
    "host": "localhost:1234",
    "basePath": "/",
    "paths": {
        "/api/v1/agent/alive": {
            "get": {
                "produces": [
                    "text/plain"
                ],
                "tags": [
                    "Ops"
                ],
                "operationId": "agent/alive",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.IsAliveResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/agent/authconfig": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Ops"
                ],
                "summary": "Returns the OAuth2 configuration of the node.",
                "operationId": "agent/authconfig",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.GetAgentNodeAuthConfigResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/agent/config": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Ops"
                ],
                "summary": "Returns the current configuration of the node.",
                "operationId": "agent/config",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/types.Bacalhau"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/agent/debug": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Ops"
                ],
                "summary": "Returns debug information on what the current node is doing.",
                "operationId": "agent/debug",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.DebugInfo"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/agent/node": {
            "get": {
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Ops"
                ],
                "summary": "Returns the info of the node.",
                "operationId": "agent/node",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.NodeInfo"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/agent/version": {
            "get": {
                "description": "See https://github.com/bacalhau-project/bacalhau/releases for a complete list of `gitversion` tags.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Ops"
                ],
                "summary": "Returns the build version running on the server.",
                "operationId": "agent/version",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.GetVersionResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs": {
            "get": {
                "description": "Returns a list of jobs.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns a list of jobs.",
                "operationId": "orchestrator/listJobs",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Namespace to get the jobs for",
                        "name": "namespace",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Limit the number of jobs returned",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Token to get the next page of jobs",
                        "name": "next_token",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Reverse the order of the jobs",
                        "name": "reverse",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Order the jobs by the given field",
                        "name": "order_by",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListJobsResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            },
            "put": {
                "description": "Submits a job to the orchestrator.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Submits a job to the orchestrator.",
                "operationId": "orchestrator/putJob",
                "parameters": [
                    {
                        "description": "Job to submit",
                        "name": "putJobRequest",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/apimodels.PutJobRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.PutJobResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/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.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Compares a job spec with an existing job of the same name.",
                "operationId": "orchestrator/diffJob",
                "parameters": [
                    {
                        "description": "Job spec to compare with existing job",
                        "name": "diffJobRequest",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/apimodels.DiffJobRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.DiffJobResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}": {
            "get": {
                "description": "Returns a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns a job.",
                "operationId": "orchestrator/getJob",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID to get the job for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "history and executions options. Empty includes nothing",
                        "name": "include",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Number of items to fetch. Use with include parameter",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Job version to get. Defaults to 0.",
                        "name": "job_version",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.GetJobResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            },
            "delete": {
                "description": "Stops a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Stops a job.",
                "operationId": "orchestrator/stopJob",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID to stop the job for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Reason for stopping the job",
                        "name": "reason",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.StopJobResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/executions": {
            "get": {
                "description": "Returns the executions of a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns the executions of a job.",
                "operationId": "orchestrator/jobExecutions",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID to get the job executions for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Namespace to get the jobs for",
                        "name": "namespace",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Limit the number of executions returned",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Token to get the next page of executions",
                        "name": "next_token",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Reverse the order of the executions",
                        "name": "reverse",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Order the executions by the given field",
                        "name": "order_by",
                        "in": "query",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListJobExecutionsResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/history": {
            "get": {
                "description": "Returns the history of a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns the history of a job.",
                "operationId": "orchestrator/listHistory",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID to get the job history for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Limit the number of history events returned",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Only return history since this time",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Only return history of this event type",
                        "name": "event_type",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Only return history of this execution ID",
                        "name": "execution_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Token to get the next page of the history events",
                        "name": "next_token",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListJobHistoryResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/logs": {
            "get": {
                "description": "Establishes a WebSocket connection to stream output from the job specified by `id`\nThe stream will continue until either the client disconnects or the execution completes",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/octet-stream"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Streams the logs for a current job/execution via WebSocket",
                "operationId": "orchestrator/logs",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID of the job to stream logs for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Fetch logs for a specific execution",
                        "name": "execution_id",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Fetch historical logs",
                        "name": "tail",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Follow the logs",
                        "name": "follow",
                        "in": "query"
                    }
                ],
                "responses": {
                    "101": {
                        "description": "Switching Protocols to WebSocket",
                        "schema": {
                            "$ref": "#/definitions/models.ExecutionLog"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/rerun": {
            "put": {
                "description": "Reruns a job with the specified job ID or name.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Reruns a job.",
                "operationId": "orchestrator/rerunJob",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID or name of the job to rerun",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Request to rerun job",
                        "name": "rerunJobRequest",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/apimodels.RerunJobRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.RerunJobResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/results": {
            "get": {
                "description": "Returns the results of a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns the results of a job.",
                "operationId": "orchestrator/jobResults",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID to get the job results for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListJobResultsResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/jobs/{id}/versions": {
            "get": {
                "description": "Returns the versions of a job.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns the versions of a job.",
                "operationId": "orchestrator/jobVersions",
                "parameters": [
                    {
                        "type": "string",
                        "description": "ID or Name to get the job versions for",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Namespace of the job",
                        "name": "namespace",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Limit the number of job versions returned",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Token to get the next page of job versions",
                        "name": "next_token",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Reverse the order of the job versions",
                        "name": "reverse",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Order the job versions by the given field",
                        "name": "order_by",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListJobVersionsResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "/api/v1/orchestrator/nodes": {
            "get": {
                "description": "Returns a list of orchestrator nodes.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Orchestrator"
                ],
                "summary": "Returns a list of orchestrator nodes.",
                "operationId": "orchestrator/listNodes",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "Limit the number of node returned",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Token to get the next page of nodes",
                        "name": "next_token",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Reverse the order of the nodes",
                        "name": "reverse",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Order the nodes by given field",
                        "name": "order_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter Approval",
                        "name": "filter_approval",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter Status",
                        "name": "filter-status",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/apimodels.ListNodesResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "type": "string"
                        }
                    },
        

# --- truncated at 32 KB (123 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/expanso/refs/heads/main/openapi/bacalhau-openapi-original.json
Bacalhau Orchestrator API

Documentation

Specifications

Other Resources

OpenAPI Specification
