Timekit developers

POST Query availability

Query for availability of resources

Fetch availability of your resources in the form of timeslots. The availability engine is quite flexible and allows you to handle complex use-cases with different constraints across many resources.

Responses from this endpoint are cached for 60 seconds. See Caching Availability for how the cache works.

Project ID

With our project model, you can predefine which parameters are used to query availability. If your integration with Timekit is based on projects, simply use the ID of the project instead of setting the parameters directly in the call.
Please refer to our Projects overview.

Mode

When calculating availability for one or more resources, you need to choose a strategy for how you want timeslots returned. This is specified by the mode parameter, which have the following options:

mode is required, unless you send a project_id for a project that has a mode set. A request without a valid mode is rejected with a 422 error.

Round-robin random
roundrobin_random is used when you want any of the specified resources to be available. It shuffles the resources array, then calculates each resource's availability and finally returns a list of timeslots with a single bookable resource per timeslot. The returned resource for a given timeslot is random based on the initial shuffle of the list of bookable resources. This can be used when you have a pool of resources, e.g. a team of salespeople, but you only need to book one of them.

Round-robin prioritized
roundrobin_prioritized is same as above, but will respect the order of the resources you supply in the resources array and favor the first one if multiple resources are availability at a given time.

Exclusive
exclusive returns all resources UUIDs that are available at the specified time provided. Whereas Round-robin random selects a resource at random and and Round-robin prioritized selects a resource in a particular order, Exclusive can be used to return every resource so that you can select one, several, or all of them to be displayed to give you a choice.

Mutual
mutual searches for overlapping timeslots where all of the specified resources need to be available. Ideal for use-cases like meetings with multiple participants or rooms that require equipment to be accessible.
Note that there can only be one resource that is "owns" the created booking, so if you need to include more resources in the booking, make sure to add them as participants to the final event to make sure their calendar is blocked too.

Constraints

At the heart of the availability engine is what we call "constraints": business rules that reduces the available ranges of time that a given resource can be available. In the most common use-cases, these are exemplified as opening hours e.g. a resource should only be a available certain days (monday-tuesday) and at certain times (1pm-5pm).

The constraints that you specify in the constraints parameter are applied dynamically to each resource in the resources array. This is in addition to the constraints that you might have defined on the globally on resource model outside of the POST /availability request, see POST /resources for how to set a resource's availability.

We do not check for logical blockage on constraints in relation to the search space, this is up to you to check for. For example if your search space consists of just two days, e.i. "from":"now", "to":"2 days" and use the constraint "block_weekends" and you request the endpoint on a saturday morning, you will get no results and you will get no errors or warnings.

Buffer Time

The buffer option makes sure that you have some breathing time between any existing events in your calendars, and the available time-slots offered. Once an available time-slot has been booked and turned into a calendar event, additional buffer time will be added to it, when querying for availability.

You define buffer like you define length: "15 minutes", "1 hour" etc.

In mutual mode, the buffer is also added around time blocked by constraints (for example the time outside opening hours), so each open period starts later and ends earlier by the buffer amount.

Timeslot increments

By default, the algorithm will return sequential time-slots. The time-slots will not overlap, which means that some potential time-slots are ignored. If you want overlapping time-slots you define the increment from the previous time-slot start with this setting.

Example without timeslot_increments:

If we request time-slots of 1 hours length, from 10 to 12, without timeslot_increments defined, these 2 time-slots will be returned:
10:00-11:00
11:00-12:00

Examples with timeslot_increments:

If we request with timeslot_increments: "15 minutes", these 5 time-slots will be returned:
10:00-11:00
10:15-11:15
10:30-11:30
10:45-11:45
11:00-12:00

If we request with timeslot_increments: "30 minutes", these 3 time-slots will be returned:
10:00-11:00
10:30-11:30
11:00-12:00

Example scenario: You want a 15 min meeting that starts at 00 and 30 only.

Supposing we review a sample availability 12:00 pm to 2:00pm.
If you check for availability using 30 mins increments for this, you would see
12:00
12:30
1:00
1:30
If you booked a 15 min meeting at 12:00, then 12:00 - 12:15 is booked. Subsequently, if you check for availability again using 30 min increments, it would appear like this:

12:15 - 12:45
12:45 - 1:15
1:15 - 1:45

Increments work on availability, so Timekit sees that the first availability is 12:15 and then increments 30 mins from there.

As a possible alternative, if you wanted meetings to be only available at 00 and 30, then you could add a 15 min buffer to your 15 min meeting, and make a PUT call to the Project endpoint with something like this:

json
{
        "mode": "roundrobin_random",
        "length": "15 minutes",
        "from": "1 hour",
        "to": "4 weeks",
        "buffer": "15 minutes",
        "ignore_all_day_events": false,
        "timeslot_increments":"30 minutes"
}

Endpoint

POST https://api.timekit.io/v2/availability

Parameters

Name In Type Required Default Description
project_id body string If you're using our projects model, specify the project ID and all parameters to the endpoint will be retrieved dynamically from the project. Any additional parameters in the request are not required and will override those set in the project.
mode body string Specify the type of availability you want calculated and returned, valid modes are: "mutual", "exclusive", "roundrobin_random", "roundrobin_prioritized". Required unless the project in project_id has a mode set.
resources body array_string Array of resource IDs that should be included in the availability search. Required unless the project in project_id has resources. Every ID must belong to your app.
constraints body array_object Array of constraint objects that either whitelist or blacklist timespans. These constraints are dynamically applied for each resource. Please ready about constraints for reference
length body string How long each available time-slot should be (minimum 1 second). If you omit it (and the project does not set one), the endpoint returns free periods of varying length instead of fixed-length time-slots. To get this, leave the key out: sending null or "Null" is rejected.
from body string Now Defines the beginning of the search-space written is human language, eg. "1 day", "2 weeks" or "tomorrow". Must be before to. If you send timestamps for both from and to, use the same UTC offset for both.
to body string 4 weeks Defines the end of the search-space written is human language, eg. "1 day", "2 weeks" or "tomorrow" (max 12 months). When length is set, the space between from and to must be at least length.
buffer body string 0 mins The amount of buffer time you want to pad around existing events (see note). Cannot be negative.
ignore_all_day_events body boolean false Set to true if all day events in your calendars should NOT be counted as blocked/unbookable (see note above)
output_timezone body string UTC If you want the outputted time-slots to be formatted to a particular timezone, set it with this parameter. Please note that this parameter will not affect the resource-relative timezones of the constraints. Please see our constraints section for further information.
timeslot_increments body string Define at which time increments the time-slots should start (minimum 5 minutes). Please see the note
round_to_nearest_hour body boolean true By default from and to are both rounded up to the next whole hour (for pretty timestamps). If you don't want this, set it to false

Request examples

curl
curl --request POST \
  --url https://api.timekit.io/v2/availability \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
           "project_id": "68b7m193-2a68-41c6-bdd4-c0ca5b35ops5"
         }'

curl
curl --request POST \
  --url https://api.timekit.io/v2/availability \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
           "mode": "roundrobin_random",
           "resources": [
             "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3"
           ],					 
           "length": "4 hours",
           "from": "3 days",
           "to": "4 weeks",
           "buffer": "30 minutes",
           "ignore_all_day_events": true
         }'

Response examples

200

json
{
  "data": [
    {
      "start": "2018-12-07T00:00:00+01:00",
      "end": "2018-12-07T04:00:00+01:00",
      "resources": [
        {
          "id": "22e8c963-2a13-4809-9601-dee0129a5aca",
          "name": "Marty McFly",
          "timezone": "Europe\/Stockholm"
        }
      ]
    },
    {
      "start": "2018-12-07T04:00:00+01:00",
      "end": "2018-12-07T08:00:00+01:00",
      "resources": [
        {
          "id": "22e8c963-2a13-4809-9601-dee0129a5aca",
          "name": "Marty McFly",
          "timezone": "Europe\/Stockholm"
        }
      ]
    },
    {
      "start": "2018-12-07T08:00:00+01:00",
      "end": "2018-12-07T12:00:00+01:00",
      "resources": [
        {
          "id": "22e8c963-2a13-4809-9601-dee0129a5aca",
          "name": "Marty McFly",
          "timezone": "Europe\/Stockholm"
        }
      ]
    }
  ]
}

422

json
{
  "errors": {
    "query": [
      "The query field is required."
    ]
  }
}
Last edited 6 October 2026.