> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keebai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/scheduling/availability

> Availability for a specific date. Returns free slots per professional for a given service.

Computes the free slots for a service on a single date. The engine takes into account professional schedules, existing appointments, service buffers (`bufferBefore`, `bufferAfter`), and time restrictions (`time_rules.earliest_start`, `time_rules.latest_end`). If no `branchId` is provided, the tenant's first branch is used.

## Endpoint

```
GET https://api.keebai.com/v1/scheduling/availability
```

## Required scope

`scheduling:availability:read`

## Query params

| Param            | Type     | Required | Description                                                                                   |
| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `serviceId`      | `string` | Yes      | Service to book. Defines slot duration and restrictions.                                      |
| `date`           | `string` | Yes      | Date in `YYYY-MM-DD` format. If earlier than today in the branch's tz, returns `results: []`. |
| `branchId`       | `string` | No       | Branch. If omitted, the tenant's first branch is used.                                        |
| `professionalId` | `string` | No       | Restrict the computation to a specific professional.                                          |

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -G https://api.keebai.com/v1/scheduling/availability \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --data-urlencode "serviceId=65b1c2d3e4f5a6b7c8d9e0f1" \
    --data-urlencode "branchId=65a1f2b3c4d5e6f7a8b9c0d1" \
    --data-urlencode "date=2026-05-02"
  ```

  ```js JavaScript theme={null}
  const url = new URL("https://api.keebai.com/v1/scheduling/availability");
  url.searchParams.set("serviceId", serviceId);
  url.searchParams.set("branchId", branchId);
  url.searchParams.set("date", "2026-05-02");

  const { results } = await (
    await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` },
    })
  ).json();
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.get(
      "https://api.keebai.com/v1/scheduling/availability",
      headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
      params={
          "serviceId": service_id,
          "branchId": branch_id,
          "date": "2026-05-02",
      },
      timeout=10,
  )
  resp.raise_for_status()
  results = resp.json()["results"]
  ```
</CodeGroup>

## Response

### 200 OK

```json theme={null}
{
  "results": [
    {
      "id": "66c1d2e3f4a5b6c7d8e9f0a1",
      "name": "María",
      "last_name": "Soto",
      "timeSlots": [
        { "time": "09:00" },
        { "time": "09:30" },
        { "time": "10:00" }
      ]
    }
  ]
}
```

| Field                        | Type     | Description                                   |
| ---------------------------- | -------- | --------------------------------------------- |
| `results[].id`               | `string` | Professional id.                              |
| `results[].timeSlots[].time` | `string` | Slot start time (`HH:mm`) in the branch's tz. |

### 400 Bad Request

`date` with an invalid format, missing `serviceId`, or no branch exists for the tenant.

### 401 Unauthorized · 403 Forbidden

Same semantics as the rest of the public API.

## Common patterns

### "Date → professional → time" picker UI

1. The user picks a date.
2. Your app calls `GET /availability?date=<date>&serviceId=...&branchId=...`.
3. The response groups slots by professional, ready to render as columns or rows.


## OpenAPI

````yaml GET /v1/scheduling/availability
openapi: 3.0.0
info:
  title: Keebai Public API
  description: Superficie pública REST autenticada con Personal Access Tokens (PAT).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.keebai.com
    description: Production
security: []
tags: []
paths:
  /v1/scheduling/availability:
    get:
      tags:
        - scheduling-availability
      summary: Disponibilidad por fecha específica
      description: Retorna los slots libres para un servicio en una fecha puntual.
      operationId: PublicAvailabilityController_byDate
      parameters:
        - name: serviceId
          required: true
          in: query
          description: Servicio (requerido)
          schema:
            type: string
        - name: date
          required: true
          in: query
          description: Fecha en formato YYYY-MM-DD
          schema:
            example: '2026-05-02'
            type: string
        - name: branchId
          required: false
          in: query
          description: 'Sucursal (default: primera del tenant)'
          schema:
            type: string
        - name: professionalId
          required: false
          in: query
          description: Profesional específico
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAvailabilityResponseDto'
      security:
        - PAT: []
components:
  schemas:
    PublicAvailabilityResponseDto:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicAvailabilitySlotDto'
      required:
        - results
    PublicAvailabilitySlotDto:
      type: object
      properties:
        start:
          type: string
          description: Hora de inicio (HH:mm) o ISO 8601
        end:
          type: string
          description: Hora de fin (HH:mm) o ISO 8601
        professional_id:
          type: string
          description: Profesional que cubre el slot
        branch_id:
          type: string
      required:
        - start
  securitySchemes:
    PAT:
      scheme: bearer
      bearerFormat: kbai_pk_<hex>
      type: http
      description: >-
        Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal
        con permiso `developer.manage_tokens`.

````