API usage

To interact with the Timefold APIs you need to authenticate with a valid API key. In the Timefold Platform you can configure API access and learn about the API specifications.

API keys

Generating API keys

Click on the drop-down next to your username, select API keys to access the API Keys available for your tenant.

Click “Create API Key” to generate a new API Key. When generating a key you define:

  • Which of your tenant’s models the key has access to. If you don’t select a model, the key can be used for any model on the tenant. We recommend you create one key for each model you use.

  • An expiration date. If you don’t pick a date, the key will expire after 7 days.

  • A maximum number of hourly executions as well as a maximum number of concurrent executions. This way you can make sure the API Key doesn’t use too many resources.

  • A name for your API key. You could use this to separate production from sandbox API keys.

All API Keys generated for a tenant are visible for all administrators of the tenant. An API Key doesn’t have any user context and is purely connected to the tenant (and optionally to the models of the tenant).

Revoking API keys

From the API Keys overview table you can delete existing keys. This can be done if an API Key is no longer needed, or if an API Key has leaked. Once an API Key is deleted, all subsequent API calls where the key is used will fail.

Timefold Model API’s

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

Explore the model 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.

Model 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

Testing the model APIs

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.

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.

POST the dataset to request a solution.

The solution can be seen by navigating to the model’s runs page and selecting the run, or you can GET the solution from the API by providing the run ID from the previous post operation.

Solver statuses

The solver could be in one of several states:

  • Scheduled (SOLVING_SCHEDULED): The data has been received and is in the queue to be solved.

  • Started (SOLVING_STARTED): The input data is being converted into the planning problem and augmented with additional information, such as distance matrix (if applicable).

  • Solving (SOLVING_ACTIVE): The planning problem is currently being solved.

  • Incomplete (SOLVING_INCOMPLETE): A full solution was not found before the run was terminated.

  • Completed (SOLVING_COMPLETED): Solving has completed and no further solution will be generated.

  • Failed (SOLVING_FAILED): An error has occurred and solving was unsuccessful.

Dealing with large payloads

For large payloads, such as submitting a planning problem, it can be useful to send a compressed request body to reduce the size of the request. The API supports gzip compressed payloads. When sending the API request, set the Content-Encoding header to gzip and send your zipped file as binary data. Similarly, when requesting data from the API, if the header Accept-Encoding is set to gzip, the response payload is compressed.