# List free times

Source: https://developers.weerom.com/docs/reference/availability/listAvailability

```http
GET https://api.weerom.com/v1/availability
```

The times a customer can book a service, for one day or up to 14 in a row. Leave `staff_id` out to get the free times of everyone who does the service. A slot is free now and may be gone a moment later: booking it answers 409 `slot_taken` when someone was faster.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | query | string | yes | The first day, as the shop's own calendar has it: 2026-11-30. At most 10 characters. |
| `days` | query | integer | no | How many days from `date` on. 1 to 14, default `1`. |
| `service_id` | query | string (uuid) | yes | The service to book. |
| `staff_id` | query | string (uuid) | no | Only this staff member's free times. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].ends_at` | string (date-time) | When an appointment in this slot would end. |
| `data[].object` | `slot` |  |
| `data[].service_id` | string (uuid) | The service the slot is for. |
| `data[].staff_id` | string (uuid) | Who would do it. |
| `data[].starts_at` | string (date-time) | Send this as `starts_at` to book the slot. |
| `has_more` | boolean | Whether another page follows this one. |
| `next_cursor` | string or null | Send as `cursor` for the next page. Null on the last. |
| `object` | `list` |  |

Example:

```json
{
  "data": [
    {
      "ends_at": "2026-11-30T09:45:00.000Z",
      "object": "slot",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-30T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "object": "list"
}
```

### 400

A parameter or a field is missing or malformed.

### 401

No key, an unknown key or a revoked key.

### 403

The shop's plan does not include the API, or this kind of key may not call this.

### 429

Too many requests. Retry-After says when.

Every error answers `{ "error": { "code", "message", "param", "request_id" } }`. `param` is only on some 400 answers. See [Errors](https://developers.weerom.com/docs/errors).

## Keys

Every kind of key: read key, write key and public key.

## Sort

By `starts_at`, earliest first, then by `staff_id`. The order is fixed.

## Filters

- `date` is a day on the shop's own calendar, not a UTC day. With `days`, the list covers that day and the days after it, `days` in all.
- `staff_id` keeps one person's times. A staff member who is inactive, unknown or does not do the service gives an empty list, not an error.

## What it does

- The times are the ones the shop's own booking form offers: its opening hours, each person's hours and breaks, bookings already made, and the lead time. Times that have passed are left out.
- Without `staff_id`, the list holds the times of every active staff member who does the service. One time can show up once per person.
- The whole list fits on one page: `has_more` is `false` and `next_cursor` is `null`. The list takes no `limit`, `cursor` or `order`, and sending one answers 400 `invalid_request`.

## Errors

Besides 401 for a missing, unknown or removed key, 403 `plan_required`, 429 `rate_limited` and 500 `internal_error`, which every endpoint can answer:

| Status | `code` | When | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | `date` is not a day, `days` is out of range, or `service_id` is missing. | Send `date` as a day such as `2026-11-30` and `days` from 1 to 14. |
| 404 | `not_found` | The service does not exist or is inactive. | Read `GET /services` and pick an active service. |
