Querying time slot availability is one of the most common operations when integrating with the Minha Agenda Virtual API. This tutorial covers all query scenarios.

Main endpoint

GET /api/v3/available-date-times/

Required parameters

Parameter	Type	Description
`calendar_key`	UUID	Calendar key
`day`	date	Date in `YYYY-MM-DD` format

Optional parameters

Parameter	Type	Description
`service_keys`	UUID[]	Filter by specific services
`action_new_appointment`	string	Action type (see table below)
`min_vacancies_available`	number	Minimum available vacancies (default: 1)
`is_manual`	boolean	Include only manually created time slots

`action_new_appointment` values

Value	Description
`new`	Available times without restrictions
`client`	Times considering client restrictions
`waiting`	Times with waiting list
`force`	Booking in already occupied slots

Basic query

curl -X GET "https://minhaagendavirtual.com.br/api/v3/available-date-times/?calendar_key=abc12345-...&day=2026-06-10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "count": 10,
  "results": [
    {
      "start_date": "2026-06-10T08:00:00-03:00",
      "end_date": "2026-06-10T08:30:00-03:00",
      "vacancies_available": 3
    },
    {
      "start_date": "2026-06-10T08:30:00-03:00",
      "end_date": "2026-06-10T09:00:00-03:00",
      "vacancies_available": 2
    }
  ]
}

Filter by service

To see time slots compatible with specific services:

curl -X GET "https://minhaagendavirtual.com.br/api/v3/available-date-times/?calendar_key=abc12345-...&day=2026-06-10&service_keys=srv12345-..." \
  -H "Authorization: Bearer YOUR_TOKEN"

You can filter by multiple services by repeating the parameter:

?service_keys=srv-1&service_keys=srv-2

Query multiple days

The API returns time slots for one day at a time. To query a week, make multiple requests:

import os
import requests
from datetime import date, timedelta

BASE_URL = "https://minhaagendavirtual.com.br/api/v3"
HEADERS = {"Authorization": f"Bearer {os.environ['EAGENDA_TOKEN']}"}
CALENDAR_KEY = "abc12345-1234-5678-9abc-def012345678"

start = date(2026, 6, 10)
available_slots = []

for i in range(7):
    day = start + timedelta(days=i)
    response = requests.get(
        f"{BASE_URL}/available-date-times/",
        headers=HEADERS,
        params={
            "calendar_key": CALENDAR_KEY,
            "day": day.isoformat(),
        }
    ).json()

    for slot in response["results"]:
        available_slots.append(slot)
        print(f"{slot['start_date']} — {slot['vacancies_available']} vacancy(ies)")

Random time slots

For scenarios where the client accepts any available time (e.g., next available slot):

GET /api/v3/available-date-times/random/

curl -X GET "https://minhaagendavirtual.com.br/api/v3/available-date-times/random/?calendar_key=abc12345-...&quantity=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Specific parameters

Parameter	Type	Description
`quantity`	number	Number of time slots to return (default: 1)
`start_date`	datetime	Minimum date/time
`end_date`	datetime	Maximum date/time

Query days with availability

To find out which days of the month have available time slots:

GET /api/v3/days/

curl -X GET "https://minhaagendavirtual.com.br/api/v3/days/?calendar_key=abc12345-...&start_date=2026-06-01&end_date=2026-06-30" \
  -H "Authorization: Bearer YOUR_TOKEN"

Use this endpoint to build a visual calendar showing the user which days are available before querying specific time slots.

Implementation tips

Moderate caching — Time slots change frequently. Don’t cache for more than 1-2 minutes
Verify before booking — Always confirm availability just before creating the appointment, as another client may have booked the slot
Use action_new_appointment=client — To respect scheduling rules set by the administrator
Pagination — For calendars with many time slots, use page and page_size to paginate results