Booking API

A booking API you can build a product on

Two calls ship the whole flow: check availability, then create the booking. Webhooks, Stripe payments, and an OpenAPI 3.1 spec included. Free to start.

Get API key free Read the docs

Create your first booking in 3 steps

Check availability, create a booking, get a confirmation. That's the entire flow.

# Step 1: Check available slots (public, no auth required)
curl "https://api.astrocal.dev/v1/availability?event_type_id=evt_abc123&start=2026-06-15&end=2026-06-15&timezone=America/New_York"

# Response

{
"event_type_id": "evt_abc123",
"timezone": "America/New_York",
"slots": [
{ "start_time": "2026-06-15T09:00:00Z", "end_time": "2026-06-15T09:30:00Z" },
{ "start_time": "2026-06-15T10:30:00Z", "end_time": "2026-06-15T11:00:00Z" },
{ "start_time": "2026-06-15T14:00:00Z", "end_time": "2026-06-15T14:30:00Z" }
]
}

# Step 2: Create a booking

curl -X POST "https://api.astrocal.dev/v1/bookings" \
-H "Authorization: Bearer ac*live*..." \
-H "Content-Type: application/json" \
-d '{
"event_type_id": "evt_abc123",
"start_time": "2026-06-15T14:00:00Z",
"invitee_name": "Alex Johnson",
"invitee_email": "alex@example.com",
"invitee_timezone": "America/New_York"
}'

# Confirmation response

{
"id": "bkg_7f3a9c2e",
"status": "confirmed",
"start_time": "2026-06-15T14:00:00Z",
"end_time": "2026-06-15T14:30:00Z",
"invitee_name": "Alex Johnson",
"invitee_email": "alex@example.com",
"created_at": "2026-06-04T09:12:00Z"
}

Core booking endpoints

Six endpoints cover every scheduling workflow. Full reference in the API docs.

POST/v1/bookingsCreate a new booking

Request

{
  "event_type_id": "evt_abc123",
  "start_time": "2026-06-15T14:00:00Z",
  "invitee_name": "Alex Johnson",
  "invitee_email": "alex@example.com",
  "invitee_timezone": "America/New_York"
}

Response

{
  "id": "bkg_7f3a9c2e",
  "status": "confirmed",
  "start_time": "2026-06-15T14:00:00Z",
  "end_time": "2026-06-15T14:30:00Z",
  "invitee_name": "Alex Johnson",
  "invitee_email": "alex@example.com",
  "created_at": "2026-06-04T09:12:00Z"
}

GET/v1/bookingsList bookings with cursor pagination (starting_after + limit)

Response

{
  "data": [
    {
      "id": "bkg_7f3a9c2e",
      "status": "confirmed",
      "start_time": "2026-06-15T14:00:00Z"
    },
    {
      "id": "bkg_4d1b8e7a",
      "status": "confirmed",
      "start_time": "2026-06-16T10:00:00Z"
    }
  ],
  "has_more": true
}

GET/v1/bookings/{id}Get full booking details

Response

{
  "id": "bkg_7f3a9c2e",
  "status": "confirmed",
  "start_time": "2026-06-15T14:00:00Z",
  "end_time": "2026-06-15T14:30:00Z",
  "invitee_name": "Alex Johnson",
  "invitee_email": "alex@example.com",
  "invitee_timezone": "America/New_York",
  "event_type": {
    "id": "evt_abc123",
    "title": "Discovery Call",
    "duration": 30
  },
  "created_at": "2026-06-04T09:12:00Z"
}

POST/v1/bookings/{id}/rescheduleReschedule an existing booking

Request

{
  "new_start_time": "2026-06-16T10:00:00Z"
}

Response

{
  "id": "bkg_7f3a9c2e",
  "status": "rescheduled",
  "start_time": "2026-06-16T10:00:00Z",
  "end_time": "2026-06-16T10:30:00Z",
  "rescheduled_at": "2026-06-04T11:00:00Z"
}

POST/v1/bookings/{id}/cancelCancel a booking (idempotent, safe to retry)

Request

{
  "reason": "Customer requested cancellation"
}

Response

{
  "id": "bkg_7f3a9c2e",
  "status": "cancelled",
  "cancelled_at": "2026-06-04T11:30:00Z"
}

GET/v1/availabilityCheck available time slots for an event type (public, no auth)

Response

{
  "event_type_id": "evt_abc123",
  "timezone": "America/New_York",
  "slots": [
    {
      "start_time": "2026-06-15T09:00:00Z",
      "end_time": "2026-06-15T09:30:00Z"
    },
    {
      "start_time": "2026-06-15T10:30:00Z",
      "end_time": "2026-06-15T11:00:00Z"
    },
    {
      "start_time": "2026-06-15T14:00:00Z",
      "end_time": "2026-06-15T14:30:00Z"
    }
  ]
}

Full API reference

Request parameters

Key fields for the POST /v1/bookings endpoint.

Key parameters

Name	Type	Default	Description	Required
event_type_id	string	—	The ID of the event type to book. Determines duration, availability rules, and host calendar.
start_time	string	—	ISO 8601 timestamp for the booking start time. Must match an available slot from GET /v1/availability.
invitee_name	string	—	Full name of the person booking the appointment.
invitee_email	string	—	Email address for confirmation and calendar invite delivery.
invitee_timezone	string	—	IANA timezone for the invitee (e.g. America/New_York). Used in confirmation emails and calendar invites. Defaults to UTC.	—
notes	string	—	Optional message from the invitee. Included in confirmation emails and visible in the dashboard.	—
metadata	object	—	Arbitrary key-value pairs attached to the booking. Useful for tracking source, campaign, or internal IDs.	—

View full API reference

Why developers choose Astrocal's booking API

Every scheduling API looks the same in the docs. Here's where the differences show up in practice.

Most scheduling tools treat their API as an afterthought: a way to pull booking data into a CRM, not a first-class way to build scheduling features. Astrocal was designed API-first from day one. The dashboard is a consumer of the same API you use.

Calendly API

Calendly's API has no endpoint to create a booking, so you can read scheduling data but not build booking into your own product. Webhook notifications require a paid plan, and rate limits are not documented publicly. There is no OpenAPI spec. The full Astrocal vs Calendly comparison covers this in detail.

Cal.com API

Cal.com is open source and the self-hosted version gives you full database access, but that requires running and maintaining your own infrastructure. The managed cloud plan gates certain API features. If you want a managed service with full API access and no ops overhead, that's a meaningful difference.

Acuity Scheduling API

Acuity's API is locked to the Powerhouse plan at $61/month. The API itself is REST-based but uses a proprietary auth scheme and has no OpenAPI spec or MCP server, so AI agent integrations need custom glue code.

Astrocal

Full read/write REST API on the free plan. OpenAPI 3.1 spec auto-generated from the codebase: always accurate, always importable into Postman, Insomnia, or any code generator. Documented rate limits (30 req/min on free, 500 req/min on Grow). Signed webhooks on all plans including free. MCP server included so AI agents can use the exact same booking API without any extra integration work. No self-hosting required.

What's included with every API key

No plan gating on the features that matter for integrations.

📄

OpenAPI 3.1 spec

Auto-generated from the codebase and always in sync. Download it at /v1/openapi.json, import into Postman, or use it to generate typed clients in any language.

Learn more

🔔

Webhook notifications

Receive HMAC-signed HTTP POST payloads for booking.created, booking.confirmed, booking.cancelled, and booking.rescheduled. Automatic retries with exponential backoff on failure.

Learn more

🧪

Sandbox mode

Test keys (ac_test_...) run against the same API without touching real calendars or sending real emails. Switch to live keys when you're ready to deploy.

📋

Cursor pagination

All list endpoints use cursor-based pagination with starting_after and limit parameters. Reliable under high volume. No skipped or duplicated records as bookings are created between pages.

🤖

MCP server for AI agents

The @astrocal/mcp-server npm package exposes the full booking lifecycle as MCP tools. Claude, Cursor, and any MCP-compatible agent can check availability and create bookings natively.

Learn more

💳

Built-in Stripe payments

Collect deposits or full payment at booking time. Connect your Stripe account, set a price on your event type, and the API handles the payment flow before confirming the booking.

Frequently asked questions

Yes. The full REST API is available on the free plan with no time limit. Free includes 30 requests per minute and 200 requests per day. Paid plans scale up to 2,000 requests per minute and 50,000 daily requests. No credit card required to get started.

No. Astrocal is a hosted SaaS product only. The API is available at api.astrocal.dev and there is no self-hosted or on-premise option. You get the full API without managing any infrastructure.

Yes. Webhooks are available on all plans including free. Astrocal sends HMAC-SHA256 signed payloads to your endpoint for booking.created, booking.confirmed, booking.cancelled, and booking.rescheduled events. Failed deliveries are retried automatically up to 6 times with exponential backoff.

Yes, in two ways. The @astrocal/mcp-server npm package exposes the full booking lifecycle as MCP tools. AI agents using Claude, Cursor, or any MCP-compatible client can check availability and create bookings natively with no custom code. Alternatively, any agent that can make HTTP requests can call the REST API directly using the OpenAPI spec for tool definitions.

Astrocal gives you full read/write access on the free plan. Calendly restricts webhooks to paid plans and does not publish rate limits. Astrocal includes an OpenAPI 3.1 spec that's always in sync with the codebase. Calendly does not. Astrocal ships an MCP server so AI agents can use the API without any extra integration work. For a full breakdown, see the Astrocal vs Calendly comparison page.

Keep reading

Guide

Ship scheduling today

Get your API key and create your first booking in under 5 minutes.

Get started free

A booking API you can build a product on

Create your first booking in 3 steps

Core booking endpoints

Request parameters

Key parameters

Why developers choose Astrocal's booking API

Calendly API

Cal.com API

Acuity Scheduling API

Astrocal

What's included with every API key

OpenAPI 3.1 spec

Webhook notifications

Sandbox mode

Cursor pagination

MCP server for AI agents

Built-in Stripe payments

Frequently asked questions

Keep reading

API quickstart

Full API reference

Webhook notifications

SDKs & libraries

Calendar API

Astrocal vs Calendly

Ship scheduling today