Quickstart

Get up and running with Astrocal in minutes. This guide walks you through creating an event type, setting availability, and booking your first meeting.

Prerequisites

An Astrocal account — sign up if you haven't already
An API key — create one from the dashboard or follow the Authentication guide
curl or any HTTP client

1. Create an Event Type

curl -X POST https://api.astrocal.dev/v1/event-types \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "30 Minute Meeting",
    "slug": "30-min-meeting",
    "duration_minutes": 30
  }'

Save the id from the response — you'll use it in the next steps.

To let invitees choose between multiple durations (e.g., 15 or 30 minutes), pass duration_options:

curl -X POST https://api.astrocal.dev/v1/event-types \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consultation",
    "slug": "consultation",
    "duration_minutes": 30,
    "duration_options": [15, 30, 60]
  }'

duration_minutes is the default duration and must be included in duration_options.

2. Add Availability Rules

Define when this event type can be booked. This sets Monday through Friday, 9am to 5pm:

curl -X PUT https://api.astrocal.dev/v1/event-types/YOUR_EVENT_TYPE_ID/availability \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "rules": [
      {"day_of_week": 1, "start_time": "09:00:00", "end_time": "17:00:00"},
      {"day_of_week": 2, "start_time": "09:00:00", "end_time": "17:00:00"},
      {"day_of_week": 3, "start_time": "09:00:00", "end_time": "17:00:00"},
      {"day_of_week": 4, "start_time": "09:00:00", "end_time": "17:00:00"},
      {"day_of_week": 5, "start_time": "09:00:00", "end_time": "17:00:00"}
    ]
  }'

Days of week: 0 = Sunday, 6 = Saturday.

3. Check Availability

Query available slots for a date range. This is a public endpoint — no auth required:

curl "https://api.astrocal.dev/v1/availability?event_type_id=YOUR_EVENT_TYPE_ID&start=2026-03-01&end=2026-03-07&timezone=America/New_York"

For variable-duration event types, pass duration to get slots for a specific length:

curl "https://api.astrocal.dev/v1/availability?event_type_id=YOUR_EVENT_TYPE_ID&start=2026-03-01&end=2026-03-07&timezone=America/New_York&duration=60"

The response contains available time slots grouped by date.

4. Create a Booking

Book a slot. This is also a public endpoint:

curl -X POST https://api.astrocal.dev/v1/bookings \
  -H "Content-Type: application/json" \
  -d '{
    "event_type_id": "YOUR_EVENT_TYPE_ID",
    "start_time": "2026-03-02T14:00:00Z",
    "invitee_name": "Jane Doe",
    "invitee_email": "jane@doe.com",
    "invitee_timezone": "America/New_York"
  }'

The response includes a cancel_token for self-service cancellation and rescheduling.

Using an SDK Instead of curl

If you prefer a typed client over raw HTTP calls, Astrocal provides npm packages for common integration patterns:

React apps — @astrocal/react gives you a provider, hooks, and a widget component. See the React SDK guide.
Any website — @astrocal/widget is a drop-in booking widget with one script tag. See the Widget guide.
AI agents — @astrocal/mcp-server connects AI agents via the Model Context Protocol. See the MCP Integration guide.

Next Steps

Event Types — Pricing, booking caps, variable durations, and more
Bookings — Cancel, reschedule, and list bookings
Sandbox Mode — Test without affecting real data
Webhooks — Get notified when bookings are created or cancelled
MCP Integration — Let AI agents book meetings
React SDK — Provider, hooks, and widget component
Embeddable Widget — Drop-in booking widget for any website
API Reference — Full endpoint documentation