API usage

In the Timefold Platform you can configure API access as well as learn about the API specifications.

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

OpenAPI specs

Each model on the Timefold Platform has its own API. The specs of those model APIs are available via the OpenAPI Standard. If you go to a model’s documentation pages, you can dive into the API Specification in the interactive interface that allows you to test and learn about each endpoint.

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

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

You can quickly enable or disable a webhook.

For each event we will send a POST call to the specified URL.

The supported events are:

  • run completed

  • run failed

Here is an example payload of the payload when a run has completed

{
    "id": "<the-id-of-the-run>",
    "status": "SOLVING_COMPLETED", // See OpenAPI spec's `SolvingStatus` for all possible options
    "outputLink": "https://...", // Link to the API where you can fetch the run's output
    "runLink": "https://...", // Link to the API where you can fetch details about the run itself
}

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.