What is a RESTful API?

RESTful APIs operate programmatically via HTTP (defined by RFC 2616) and use a number of stateless operations (PUT, DELETE, POST, etc…) to interact with resources. Learn more about them here, or check out a tutorial here.

If you’re ready to skip ahead, go here for the full Fugue API Reference.

How Does It Work?

Fugue’s RESTful API enables users to take advantage of REST clients (Postman, Insomnia, Paw, etc.) or HTTP clients (curl) to issue Fugue commands and manage cloud infrastructure. The API benefits customers that want to integrate Fugue into new or existing workflows (e.g. CI/CD, service catalog, etc.) or those customers who may want to provide their own user interface on top of Fugue. In either scenario a user can simply issue fugue server run to launch an HTTP server and begin using commands. Learn more about the server command here.

How Do I Get Set Up?

Install Fugue & Launch a Conductor

You will need to have Fugue installed and a Conductor running. If you still need to get set up, check out the Quick Start Guide.

Note: Any server you launch is configured on your local host, and nothing is installed on the Conductor itself.

Set an Environment Variable

Export an environment variable to access the fugue server command:

export FUGUE_BETA_API=true


The Fugue API server uses Fugue user credentials for authentication. Fugue searches for the credentials file in these locations.

Authentication is handled in one of two ways. You may:

  • Pass your RBAC (Fugue) profile credentials in each HTTP request, using Basic Authentication. This scenario is useful for a setup with multiple users with differing levels of access to run commands. By default, the server runs without a credentials profile, so authentication is provided by the client. Your Fugue user (RBAC) credentials must be included in every HTTP request header.
  • Or, specify a Fugue user profile with the use of --profile when you issue the fugue server run command.
    • Note: For this option to work, the Conductor must be installed, and the profile must exist in your credentials file.

Once a server is started, if the --profile option is used, authentication passed in HTTP headers is ignored. Learn more about the server command here.

Note: If you encounter a 401 unauthorized error when attempting an action this typically indicates that your user does not have the appropriate Fugue/RBAC permissions.

AWS Credentials

You can set the AWS credentials your client uses to communicate with the Fugue API server by sending your AWS credentials or profile name as headers. For example, the following curl command passes the AWS profile name myOtherProfile to the Fugue-Aws-CredentialProfile header and requests the status of all running processes:

curl -H "Fugue-Aws-CredentialProfile: myOtherProfile"

There are four parameters:

The region the Conductor is running in
Your AWS access key ID (AKID)
Your AWS secret access key ID (SKID)
The name of your AWS credential profile

You can send the AKID and SKID together, or you can send just the profile name, but there’s no need for all three parameters in a single request.

For more information, see the API Reference.

Sending API Requests

Use your preferred client to send API requests to the Fugue API server. You can consult our API Reference for the API path and method corresponding to the Fugue command you want to execute.

For example, executing curl will return the Fugue status of all processes.

Or check out a walkthrough to learn how to use the Fugue API to create and manage a process programmatically over HTTP.

Create a Snapshot

A snapshot is an archive file that includes a composition, all of the required files to compile it, and any associated environment variables. This is the compilation output that the Conductor needs in order to create a new process. It is an output format within lwc that supports the relationship between the Fugue API and the Ludwig Compiler. The snapshot functionality is only necessary for scenarios where the Fugue Conductor will be uploading a composition including:

  • run
  • update
  • policy rbac-attach
  • policy validation-add
  • dry-run for the run and update commands

Note: Snapshot files must be suffixed .tar.gz (e.g. name.tar.gz) for the Conductor to recognize them.

Request a Dry-Run

Fugue supports dry-run on four CLI commands:

To complete a dry-run of any of these commands over API, follow these two steps:

  1. Request a dry-run
  2. Get a dry-run result

1. Request a dry-run

First, you must send an API call requesting a dry-run. The command you’re dry-running is specified as a query parameter. Other query parameters may be required, depending on the command.

For example, the following curl command requests a dry-run of a composition snapshot titled HelloWorld.tar.gz:

curl -X POST -H 'content-type: application/x-tar' --data-binary @HelloWorld.tar.gz

The API server’s response might look like this:

  "id": "2b9b08b6-61dc-422a-95d4-44fa96db0bbb.3d550a8d-ed32-4e75-a60e-ba9160fe22b4",
  "link": {
    "href": "/api/v0/dry-run/2b9b08b6-61dc-422a-95d4-44fa96db0bbb.3d550a8d-ed32-4e75-a60e-ba9160fe22b4",
    "rel": "self"
  "status": "accepted"
The ID of the results resource

Contains the href and rel fields

The path of the results resource
The link relation type – in this case, self
The status of the API call – in this case, accepted

2. Get a dry-run result

The second step of the dry-run process is to retrieve the dry-run results.

Using the path returned from the previous step, you might use a curl command like this one:


And in the response, you’d see the dry-run plan in JSON format:

  "fid": "2b9b08b6-61dc-422a-95d4-44fa96db0bbb",
  "job_id": "1511380257",
  "requests": [

Output trimmed for length.

What Is Not Supported?

Fugue does not provide RESTful API support for the following commands:

  • init
  • install
  • runtime
  • uninstall
  • upgrade
  • user
  • support

If you have questions, reach out to support@fugue.co.

Where Can I Get More Information?

For details on fugue server refer to our page on the command or check out a walk-through of the Fugue API.

Take a look at the full Fugue API Reference here.