> ## 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/next

> Closest upcoming available time slots. Walks forward from a base date until it finds N free slots.

Returns the next available slots starting from `fromDate` (default: today in the branch's tz), walking forward up to `maxDays` days and stopping once `limit` slots per professional have been collected. Designed for "first available time" flows.

## Endpoint

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

## Required scope

`scheduling:availability:read`

## Query params

| Param            | Type     | Required | Default        | Description                                                        |
| ---------------- | -------- | -------- | -------------- | ------------------------------------------------------------------ |
| `serviceId`      | `string` | Yes      | —              | Service to book.                                                   |
| `branchId`       | `string` | No       | tenant's first | Branch.                                                            |
| `professionalId` | `string` | No       | —              | Restrict to a single professional.                                 |
| `fromDate`       | `string` | No       | today          | Date to start the search from (`YYYY-MM-DD`).                      |
| `maxDays`        | `number` | No       | `14`           | Maximum number of days to walk forward. Range `1..60`.             |
| `limit`          | `number` | No       | `5`            | Maximum number of slots to return per professional. Range `1..20`. |

## Example request

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

  ```js JavaScript theme={null}
  const url = new URL("https://api.keebai.com/v1/scheduling/availability/next");
  url.searchParams.set("serviceId", serviceId);
  url.searchParams.set("branchId", branchId);
  url.searchParams.set("maxDays", "14");
  url.searchParams.set("limit", "5");

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

## Response

### 200 OK

```json theme={null}
{
  "results": [
    {
      "professional": {
        "id": "66c1d2e3f4a5b6c7d8e9f0a1",
        "name": "María",
        "last_name": "Soto"
      },
      "slots": [
        { "date": "2026-05-02", "time": "09:00" },
        { "date": "2026-05-02", "time": "09:30" },
        { "date": "2026-05-03", "time": "10:00" }
      ]
    }
  ]
}
```

| Field                    | Type     | Description                                |
| ------------------------ | -------- | ------------------------------------------ |
| `results[].professional` | `object` | Professional with id and name.             |
| `results[].slots[]`      | `array`  | Free slots ordered from soonest to latest. |

### 401 Unauthorized · 403 Forbidden

Same semantics as the rest of the public API.


## OpenAPI

````yaml GET /v1/scheduling/availability/next
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/next:
    get:
      tags:
        - scheduling-availability
      summary: Próximas horas disponibles más cercanas
      description: >-
        Busca los próximos slots libres a partir de `fromDate` (default: hoy)
        recorriendo hasta `maxDays` días.
      operationId: PublicAvailabilityController_next
      parameters:
        - name: serviceId
          required: true
          in: query
          description: Servicio (requerido)
          schema:
            type: string
        - name: branchId
          required: false
          in: query
          schema:
            type: string
        - name: professionalId
          required: false
          in: query
          schema:
            type: string
        - name: fromDate
          required: false
          in: query
          description: Fecha desde (YYYY-MM-DD)
          schema:
            type: string
        - name: maxDays
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 60
            default: 14
            type: number
        - name: limit
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 20
            default: 5
            type: number
      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`.

````