Timekit developers

POST Caching Availability

Endpoint that uses cache when fetched frequently

This endpoint works the same way as v2/availability: both endpoints take the same parameters, run the same availability query and cache their responses in the same way. You can use either one.

How does it work?

When you request availability, the response is cached. The cache entry is keyed on the endpoint and the full request body, so only an identical request (same parameters, in any order) matches it. To skip the cache for a single request, add ?cache=false to the URL.

Cache will be bursted in following scenarios:

  • When resource is updated with new constraints
  • When project is updated with new constraints
  • When new booking is created for specific resource

This endpoint will inherit your project settings if some params are not set as a payload. The exception is output_timezone, which is not taken from the project and defaults to UTC.

Modes

Timekit currently operate with four modes to query availability, these only have significance if you're querying availability for more than one resource. You must still set a mode on every request, unless the project in project_id has one set.

  • Mutual.
  • Exclusive.
  • Round-robin random.
  • Round-robin prioritized.

Mutual Mode Strategy

The mutual mode will ensure that all resources are available in a given time-slot.

Round-robin Strategy

The round-robin modes will choose whichever resource is available at a given time-slot, according to the strategy. The round-robin random strategy chooses resource randomly as the name suggests. The inner workings of Timekit's availability-algorithm dictates that once a resource has been found for a given time-slot, this resource will have precedence for the remainder of the of time-slots.

This means that you will not see random resource-allocation between the produced time-slots, only if a time-slot is found where the first randomly chosen resource is not available, will there be a different resource allocated to that particular time-slot.

The prioritized round-robin strategy works in much the same manner, except that the resource with precedence is chosen based on the sequence given when defining resources.

Exclusive Strategy

The exclusive mode will ensure that if time slot has number of assigned resources for a given time slot, it will show all available resources for that specific time slot.

If time slot has two resources and one of them already booked it will only show single resource available for this time slot. Resources are chosen based on their availability for given slot.

Endpoint

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

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.
resources body array_string Array of resource IDs that should be included in the availability search
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. In mutual mode it is also added around time blocked by constraints such as opening hours.
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 se 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
mode body string Timekit currently operate with four modes to query availability. mutual, exclusive, roundrobin_random, roundrobin_prioritized. Required unless the project in project_id has a mode set.

Request examples

curl
curl --request POST \
  --url https://api.timekit.io/v2/availabilityCached \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
      "round_to_nearest_hour": true,
      "to": "2022-05-19T17:00:00-04:00",
      "from": "2022-05-19T09:00:00-04:00",
      "output_timezone": "America/Toronto",
      "project_id": "f7df8e1e-f04b-4e3f-9376-ed82b41f4036",
      "resources": [
          "a6fc1bdb-8035-4007-919b-6276b9124eb8"
      ]
  }'

Response examples

200

json
{
    "data": [
        {
            "start": "2022-05-19T09:00:00-04:00",
            "end": "2022-05-19T09:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T09:30:00-04:00",
            "end": "2022-05-19T10:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T10:00:00-04:00",
            "end": "2022-05-19T10:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T10:30:00-04:00",
            "end": "2022-05-19T11:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T11:00:00-04:00",
            "end": "2022-05-19T11:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T11:30:00-04:00",
            "end": "2022-05-19T12:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T12:00:00-04:00",
            "end": "2022-05-19T12:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T12:30:00-04:00",
            "end": "2022-05-19T13:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T13:00:00-04:00",
            "end": "2022-05-19T13:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T13:30:00-04:00",
            "end": "2022-05-19T14:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T14:00:00-04:00",
            "end": "2022-05-19T14:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T14:30:00-04:00",
            "end": "2022-05-19T15:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T15:00:00-04:00",
            "end": "2022-05-19T15:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T15:30:00-04:00",
            "end": "2022-05-19T16:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T16:00:00-04:00",
            "end": "2022-05-19T16:30:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        },
        {
            "start": "2022-05-19T16:30:00-04:00",
            "end": "2022-05-19T17:00:00-04:00",
            "resources": [
                {
                    "name": "Sandip Patel",
                    "id": "a6fc1bdb-8035-4007-919b-6276b9124eb8",
                    "timezone": "America/Toronto"
                }
            ]
        }
    ]
}
Last edited 6 October 2026.