API usage

In the Timefold Platform you can configure API access, webhooks and learn about the API specifications.

Timefold Model API’s

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

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.

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 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.

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.

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.

Configuring webhooks

To receive near real-time updates when runs finish, go to your tenant’s Webhooks page.

  1. Click Add Webhook to create a new webhook.

  2. Enter the URL to receive event updates from your tenant.

  3. Accept the generated name or provide a name for the webhook.

webhook configuration

Optionally, you can define http-headers that Timefold will send along with the webhook, for instance, to pass on an Authorization header.

Enable or disable the webhook with the toggle.

The webhook can be configured to trigger for different events.

If the webhook is always triggered, for each event we will send a POST call to the specified URL.

The supported triggers are:

  • Successful run completed.

  • Run failed.

  • Runs with a name that matches a specific regular expression.

  • Runs that have the specified tags.

Here is an example payload that will be sent to the webhook when a run has completed:

{
  "id": "<the-id-of-the-run>",
  "name": "<name of the run>",
  "model": "field-service-routing",
  "modelVersion": "v1",
  "tags": [],
  "status": "SOLVING_COMPLETED",
  "runLink": "https://...", // Link to the API where you can fetch details about the run itself,
  "outputLink": "https://..." // Link to the API where you can fetch the run's output
}

Our platform expects the webhook URL to return HTTP Status Code 200. If the response code is different, we will try again 10 seconds later. We will retry up to 10 times.

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.

Platform Admin API

While each model has their own API (the "Model APIs" described above), the Timefold Platform itself also has an Admin API. This API can be used to make administration changes to the platform. If you don’t want to automate administration tasks, you don’t need this API. Authentication with this API is via the oAuth protocol and its endpoints are described in this OpenAPI Spec.