Nodes API provides a way to query information about the nodes in the cluster.
Endpoint: GET /api/v1/orchestrator/nodes/:nodeID
Retrieve information about a specific node.
Parameters:
:nodeID: Identifier of the node to describe. (e.g. QmUDAXvv31WPZ8U9CzuRTMn9iFGiopGE7rHiah1X8a6PkT)
Response:
Node: Detailed information about the requested node.
Example:
Endpoint: GET /api/v1/orchestrator/nodes
Retrieve a list of nodes.
Parameters:
labels: Use label-based criteria to filter nodes. See Label Filtering for usage details.
limit: Set the maximum number of jobs to return. Default is set to 10.
next_token: Utilize this parameter for pagination continuation.
order_by: Determine the ordering of jobs. Choose between id, type, available_cpu, available_memory, available_disk or available_gpu. (default is id).
reverse: Opt to reverse the default order of displayed jobs.
Response:
Nodes: List of matching nodes.
NextToken (string): Pagination token.
Example:
Find two linux nodes with most available Memory
Welcome to the official API documentation for Bacalhau. This guide provides a detailed insight into Bacalhau's RESTful HTTP APIs and demonstrates how to make the most out of them.
Bacalhau operates on an "API-first" approach, providing an interface for users to interact with the system programmatically.
Endpoint Prefix: All APIs are versioned and prefixed with /api/v1.
Default Port: By default, Bacalhau listens on port 1234.
API Nodes:
Orchestrator: Handles user requests, schedules, and monitors jobs. Majority of Bacalhau's APIs are dedicated to Orchestrator interactions. These are accessible at /api/v1/orchestrator.
Compute Nodes: Acts as worker nodes and executes the jobs. Both Orchestrator and Compute nodes expose some common APIs under /api/v1/agent for querying agent info and health status.
Bacalhau supports label filtering on certain endpoints, such as /api/v1/orchestrator/jobs and /api/v1/orchestrator/nodes. This mechanism works similarly to constraints, letting you narrow down your search based on certain criteria.
Example:
To handle large datasets, Bacalhau supports pagination. Users can define the limit in their request and then utilize the next_token from the response to fetch subsequent data chunks.
To sort the results of list-based queries, use the order_by parameter. By default, the list will be sorted in ascending order. If you want to reverse it, use the reverse parameter. Note that the fields available for sorting might vary depending on the specific API endpoint.
By default, Bacalhau's APIs provide a minimized JSON response. If you want to view the output in a more readable format, append pretty to the query string.
Being RESTful in nature, Bacalhau's API endpoints rely on standard HTTP methods to perform various actions:
GET: Fetch data.
PUT: Update or create data.
DELETE: Remove data.
The behavior of an API depends on its HTTP method. For example, /api/v1/orchestrator/jobs:
GET: Lists all jobs.
PUT: Submits a new job.
DELETE: Stops a job.
Understanding HTTP response codes is crucial. A 2xx series indicates a successful operation, 4xx indicates client-side errors, and 5xx points to server-side issues. Always refer to the message accompanying the code for more information.
The Bacalhau Agent APIs provide a convenient means to retrieve information about the Bacalhau node you are communicating with, whether it serves as the orchestrator or functions as a compute node. These APIs offer valuable insights into the node's health, capabilities, and deployed Bacalhau version.
Endpoint: GET /api/v1/agent/alive
This API can be used to determine if the agent is operational and responding as expected.
Response:
Endpoint: GET /api/v1/agent/version
This API provides details about the Bacalhau version, including major and minor version numbers, Git version, Git commit, build date, and platform information.
Response:
Endpoint: GET /api/v1/agent/node
This API provides detailed information about the node, including its peer ID and network addresses, node type (e.g., Compute), labels, compute node capabilities, and the deployed Bacalhau version.
Response:
Job APIs enables creating, managing, monitoring, and analyzing jobs in Bacalhau.
Endpoint: GET /api/v1/orchestrator/jobs/:jobID
Retrieve the specification and current status of a particular job.
Parameters:
:jobID: Identifier of the job to describe. This can be full ID of the job (e.g. j-28c08f7f-6fb0-48ed-912d-a2cb6c3a4f3a) or just the short format (e.g. j-28c08f7f) if it's unique.
Response:
Job: Specification for the requested .
Example:
Endpoint: GET /api/v1/orchestrator/jobs
Retrieve a list of jobs.
Parameters:
namespace: Specify a namespace to filter the jobs. Use * to display jobs from all namespaces.
limit: Set the maximum number of jobs to return. Default is set to 10.
next_token: Utilize this parameter for pagination continuation.
order_by: Determine the ordering of jobs. Choose between id or create_time (default is create_time).
reverse: Opt to reverse the default order of displayed jobs.
Response:
NextToken (string): Pagination token.
Example:
List jobs with limit set to 3:
List with label filtering
Endpoint: PUT /api/v1/orchestrator/jobs
Submit a new job for execution.
Request Body:
Response:
JobID (string): Identifier for the new job.
EvaluationID (string): Identifier for the evaluation to schedule the job.
Warnings (string[]): Any warnings during job submission.
Example:
Endpoint: DELETE /api/v1/orchestrator/jobs/:jobID
Terminate a specific job asynchronously.
Parameters:
:jobID: Identifier of the job to describe. This can be full ID of the job (e.g. j-28c08f7f-6fb0-48ed-912d-a2cb6c3a4f3a) or just the short format (e.g. j-28c08f7f) if it's unique.
reason: A message for debugging and traceability.
Response:
EvaluationID (string): Identifier for the evaluation to stop the job.
Example:
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/history
Retrieve historical events for a specific job.
Parameters:
since: Timestamp to start (default: 0).
event_type: Filter by event type: job, execution, or all (default).
execution_id: Filter by execution ID.
node_id: Filter by node ID.
limit: Maximum events to return.
next_token: For pagination.
Response:
History: List of matching historical events.
NextToken (string): Pagination token.
Example:
List events for a specific execution
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/executions
Retrieve all executions for a particular job.
Parameters:
limit: Maximum executions to return.
next_token: For pagination.
order_by: Order by modify_time (default), create_time, id, state.
reverse: Reverse the order.
Response:
Executions: List of relevant executions.
NextToken (string): Pagination token.
Example
List executions for a batch job with 3 executions (i.e. count=3)
Endpoint: GET /api/v1/orchestrator/jobs/:jobID/results
Fetch results published by all executions for the defined job. Applicable only for batch and ops jobs.
Response:
NextToken (string): Pagination token.
Example:
labels: Use label-based criteria to filter jobs. See for usage details.
: List of matching jobs.
: JSON definition of the job.
: List of all published results.
Result of a job that used the :