Understanding the API

Each model on the Timefold Platform has its own API which conforms with the OpenAPI standard.

1. Explore the API in the Timefold Platform UI

You can explore the API in Timefold Platform.

  1. Log in to app.timefold.ai.

  2. Select the model.

  3. Select OpenAPI Spec.

1.1. API Endpoints

To understand the API endpoints, select an endpoint to expand it. You will see:

  • Parameters: The parameters required by the API endpoint.

  • Request body: For POST endpoints, you can view example values that are accepted as part of the JSON input and the model schema.

  • Response: The responses the API endpoints will return, example values, and the schema.

The Example Value tab for each endpoint show an example of the JSON for that endpoint:

example values

The Schema tab shows the values, their types, and a description. Each field can be expanded to view related information.

schema

1.2. Testing the API

To test the API functionality in the platform, you first need to authorize the API.

  1. From the drop-down menu next to your username select API Keys.

  2. Copy an API key that has permissions for the model you want to test.

  3. Navigate back to the model you want to test and select OpenAPI Spec.

  4. Click Authorize and paste the API key you just copied.

1.3. Demo datasets

Demo datasets that demonstrate the functionality are available. To view the list of demo datasets:

  1. Expand the POST /v1/demo-data endpoint.

  2. Click Try it out, then click Execute.

You will see the Curl instructions to request the dataset and the request URL.

You will also see the response to the request with the list of available datasets.

To download one of the listed datasets:

  1. Expand the POST /v1/demo-data/{demoDataId} endpoint.

  2. Click Try it out, enter the name of the dataset, for instance, "BASIC", and click Execute.

In the response body, you will see the dataset. Copy the dataset to use with subsequent endpoints.

Alternatively, you can use your own dataset to test the functionality.

1.4. Request an employee shift schedule

To request a schedule in the Employee Shift Scheduling model:

  1. Expand the POST v1/schedules endpoint, and click Try it out.

  2. Paste the dataset from the previous call (or use your own dataset) into the request body field over the existing text and click Execute.

Note the ID in the response.

You can view the dataset as it is being solved by navigating back to the top of the page and clicking Runs. Note, it will take a few minutes to provide a solution for the dataset.

1.5. Request the schedule

To request the solution for the dataset:

  1. Expand the GET v1/schedules/{id} endpoint, and click Try it out.

  2. Paste the ID from the previous POST call into the id field.

In the response body, you will see the schedule. Note, if the schedule is still being generated, the solverStatus will be "SOLVING_ACTIVE". If the final schedule has been generated, the solverStatus will be "SOLVING_COMPLETE".