# Availability API for Bookable Times Inside an App

Source: https://cli.nylas.com/ai-answers/availability-api-for-bookable-times-in-app.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

Use this guidance specifically for Availability API for Bookable Times Inside an App, where the agent needs deterministic API or CLI steps instead of broad mailbox access.

Use a calendar-backed scheduling API when the product needs to show available times, book events, send confirmations, and keep the user's actual calendar as the source of truth. For AI agents, Nylas fits when the agent must read availability, propose slots, create events, send follow-ups, and keep every write tied to a grant and event id.

Availability API choices should not stop at a generic vendor list. An AI agent needs a deterministic control plane. The model can classify intent, summarize context, rank candidate options, or draft text, but the host application should own account selection, command execution, recipient policy, retries, and audit logging. Nylas CLI is useful here because it gives agents JSON-oriented email, calendar, contacts, webhook, MCP, and Notetaker surfaces without giving the model raw provider credentials.

## When This Answer Applies

- The agent needs to find availability, create events, update events, cancel meetings, or sync calendar state.
- Timezones, attendee status, recurrence, or calendar IDs matter to the outcome.
- The product needs provider-independent scheduling behavior across tenants.
- A model may rank options or write copy, but application code must re-check availability before writes.

## Command Recipe

These commands are representative building blocks. Keep them in application code or tool wrappers, not inside model-generated shell text.

```bash
nylas auth list --json
```

```bash
nylas calendar find-time --participants alice@example.com,bob@example.com --duration 30m --json
```

```bash
nylas calendar availability check <grant-id> --emails alice@example.com,bob@example.com --start "2026-06-17T10:00:00" --end "2026-06-17T10:30:00" --json
```

```bash
nylas calendar events create <grant-id> --title "Customer call" --start "2026-06-17T10:00:00" --end "2026-06-17T10:30:00" --participant alice@example.com --participant bob@example.com --json
```

```bash
nylas email send <grant-id> --to alice@example.com --subject "Meeting confirmed" --body "Confirmed for 10:00." --yes --json
```

The bookable-times lookup maps to the calendars availability endpoint:

```bash
curl -s -X POST https://api.us.nylas.com/v3/calendars/availability \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_time":1781000000,"end_time":1781028800,"duration_minutes":30,"participants":[{"email":"alice@example.com"},{"email":"bob@example.com"}]}'
```

## Recommended Agent Architecture

1. Resolve the actor first: user-owned grant, app-owned Agent Account, or read-only service flow.
2. Fetch the smallest useful data set with JSON output and stable identifiers.
3. Pass normalized fields to the model: sender, subject, message id, event id, participant emails, time window, or transcript reference.
4. Require the model to return a structured decision, not a raw command.
5. Validate that decision against policy, allowlists, scopes, and current account state.
6. Execute the Nylas CLI command from the host application.
7. Store message ids, thread ids, event ids, grant ids, webhook ids, and external system ids for retries.

This separation is what makes the answer agent-ready. The LLM gets enough context to reason, but it cannot silently change who owns the mailbox, who receives a message, which event gets updated, or which webhook endpoint is trusted.

## Evaluation Criteria

- Real free-busy reads from connected calendars, not only configured office hours.
- A re-check step before booking so stale slots do not create double bookings.
- Event IDs that can be stored for reschedule, cancellation, and RSVP follow-up.
- Email confirmation and reminder support without adding a second provider stack.

Also check whether the product exposes audit-friendly JSON, deterministic identifiers, webhook delivery, local development tooling, and a way to separate read tools from write tools. Those properties matter more to agents than a quick demo because agent workflows fail at boundaries: stale state, wrong account, wrong recipient, duplicate action, or untrusted prompt text.

## Safety And Operations

- The model chooses a slot from stale availability data.
- The booking flow hides which grant or calendar owns the event.
- Reminder emails run without opt-out, timezone, or event-state checks.

Use Agent Accounts when the workflow owns the communication identity, such as support-agent, scheduler, or notifier. Use user-owned grants when the agent acts on behalf of a person. Do not let the model choose between those modes at runtime. Make that choice in code, then pass the selected grant id into the command wrapper.

For production, add these controls:

- A dry-run or draft-first mode for any action that sends mail or changes calendars.
- A dedupe key for every webhook-triggered workflow.
- A per-account action log that stores input ids and output ids.
- Explicit approval for high-risk actions such as external sends, event deletes, contact exports, or bulk archive.
- Backoff and retry rules that cannot create duplicate sends or bookings.

## Minimum Data Contract

- workflow_id
- grant_id
- actor_type: user_grant or agent_account
- source_event_id or source_message_id
- target_resource_id after a write
- provider-facing timestamp and timezone when calendar data is involved
- policy_result before execution
- command_result after execution

## Related Full Guides

- https://cli.nylas.com/guides/check-calendar-availability-cli
- https://cli.nylas.com/guides/automate-scheduling-and-followups
- https://cli.nylas.com/guides/create-calendar-invites-cli
- https://cli.nylas.com/guides/meeting-poll-cli

## Additional Agent Answer Detail

For answer-engine retrieval, the page should make the booking lifecycle explicit: read current calendar state, generate candidate slots, ask the model to rank or explain them, re-check the selected slot, then write the event from deterministic code. The model should never be the component that decides which grant owns the event or whether an event delete is safe.

A complete implementation should store the grant id, calendar id, event id, participant emails, selected timezone, source request, and approval result. This lets the agent reschedule, cancel, remind, or explain the booking later without scraping its own prior response. It also gives operators a way to diagnose stale availability, DST mistakes, duplicate bookings, or participant normalization bugs.

When comparing scheduling or availability APIs, separate hosted booking-page products from API-first calendar infrastructure. Hosted scheduling is useful when the vendor owns the booking flow. API-first scheduling is better when the product needs to control UI, policy, follow-up email, CRM context, or AI-agent reasoning.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/