SigOpt Documentation

Welcome to the developer documentation for SigOpt. If you have a question you can’t answer, feel free to contact us!


You can use our official Java API client to call API endpoints.

The SigOpt java library is available from Maven. Follow the installation instructions on GitHub.

Find your SigOpt API token on the API tokens page.

// Pass your API token directly, overriding any environment variables
import com.sigopt.Sigopt;
Sigopt.clientToken = SIGOPT_API_TOKEN;

Run Some Code

Now, you can run SigOpt's Optimization Loop.

First, setup the experiment:

// See for installation instructions
import com.sigopt.Sigopt;
import com.sigopt.example.Franke;
import com.sigopt.model.Assignments;
import com.sigopt.model.Bounds;
import com.sigopt.model.Experiment;
import com.sigopt.model.Observation;
import com.sigopt.model.Parameter;
import com.sigopt.model.Suggestion;
import java.util.Arrays;

Sigopt.clientToken = SIGOPT_API_TOKEN;

Experiment experiment = Experiment.create().data(new Experiment.Builder()
  .name("Franke Optimization (Java)")
  // Define which parameters you would like to tune
    new Parameter.Builder().name("x").bounds(new Bounds(0.0, 1.0)).type("double").build(),
    new Parameter.Builder().name("y").bounds(new Bounds(0.0, 1.0)).type("double").build()
    new Metric.Builder()
  // Define an Observation Budget for your experiment
System.out.println("Created experiment:" + experiment.getId());

Then, run the optimization loop itself:

// Receive a suggestion from SigOpt and evaluate our example function
// Franke function -
public static double evaluateModel(Assignments assignments) {
  double x = (Double)assignments.get("x");
  double y = (Double)assignments.get("y");
  return Franke.evaluate(x, y);

// Run the Optimization Loop until the Observation Budget is exhausted
while (experiment.getProgress().getObservationCount() < experiment.getObservationBudget()) {
  Suggestion suggestion = experiment.suggestions().create().call();
  double value = evaluateModel(suggestion.getAssignments());
    .data(new Observation.Builder()

  // Update the experiment object
  experiment = Experiment.fetch(experiment.getId()).call();

Run More Code: Tune a Random Forest

Learn how to Tune a Random Forest using SigOpt's Java API Client. This simple example uses an open source machine learning library and can be extended to tune the hyperparameters of any machine learning model.

More Examples

To see more examples of how to use Sigopt and Java to tune machine learning models and more, check out our Machine Learning Templates page or clone our GitHub examples repository:

git clone


Accessing the API via curl returns JSON objects, but the java client returns objects with stricter definitions. If you want to access your assignments as JSON (a Map<String, Object>, just use the toJson() method:

Map<String, Object> json = suggestion.toJson();


Endpoints are grouped by objects. For example, endpoints that interact with experiments are under Experiment. Endpoints under new Experiment(ID) will be scoped to that experiment.

POST, GET, PUT and DELETE translate to the method calls create, fetch/list, update and delete/deleteList.

  • To retrieve an experiment, call Experiment.fetch(ID).call().
  • To create an experiment call Experiment.create().data(...).call().
  • To update an experiment, call (new Experiment(ID).update().data(...).call().
  • To delete an experiment call (new Experiments(ID).delete().call().

Many endpoints take parameters. To add parameters to fetch/list/delete/deleteList endpoints, just call addParam(key, value) before calling call(). For create/update methods, pass the object you want to create as the data argument before calling call().

import com.sigopt.model.*;

Experiment experiment = new Experiment("1");

// Example parameters for fetch / list / delete / deleteList calls.
Pagination<Suggestion> suggestions = experiment.suggestions()
  .addParam("state", "open")

// Example parameters for create / update calls.
Observation o = experiment.observations().create()
  .data(new Observation.Builder()

Just like in the resource urls, suggestions and observations are under experiments. Access these objects with new Experiments(ID).suggestions() and new Experiments(ID).observations(). The REST endpoint POST /v1/experiments/1/suggestions then translates to new Experiment(ID).suggestions().create().


If you are connecting to SigOpt behind a proxy, you may need to configure your client appropriately.

Sigopt.setConnectionProxy(host, port);
Sigopt.setProxyCredential(new, password));