Astrocal
Guides

Quickstart

Book your first meeting in 5 minutes.

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
  }'
const response = await fetch("https://api.astrocal.dev/v1/event-types", {
  method: "POST",
  headers: {
    Authorization: "Bearer ac_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "30 Minute Meeting",
    slug: "30-min-meeting",
    duration_minutes: 30,
  }),
});
const data = await response.json();

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]
  }'
const response = await fetch("https://api.astrocal.dev/v1/event-types", {
  method: "POST",
  headers: {
    Authorization: "Bearer ac_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Consultation",
    slug: "consultation",
    duration_minutes: 30,
    duration_options: [15, 30, 60],
  }),
});
const data = await response.json();

Try it in the API playground →

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"}
    ]
  }'
const response = await fetch(
  "https://api.astrocal.dev/v1/event-types/YOUR_EVENT_TYPE_ID/availability",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer ac_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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" },
      ],
    }),
  }
);
const data = await response.json();

Try it in the API playground →

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

3. Check Availability

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

"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"
"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"
); const data = await response.json(); ```
</Tab>
</Tabs>

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

<Tabs items={["curl", "TypeScript"]}>
<Tab value="curl">
```bash 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"
"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"
); const data = await response.json(); ```
</Tab>
</Tabs>

_[Try it in the API playground →](/docs/api-reference/availability/v1/availability/get)_

The response contains available time slots grouped by date.

## 4. Create a Booking

Book a slot. This is also a **public endpoint**:

<Tabs items={["curl", "TypeScript"]}>
<Tab value="curl">
```bash
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"
}'
const response = await fetch("https://api.astrocal.dev/v1/bookings", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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",
  }),
});
const data = await response.json();

Try it in the API playground →

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:

Next Steps

Welcome to Astrocal

The scheduling API built for AI agents and developers.

Authentication

How to authenticate with the Astrocal API using API keys.

On this page

Prerequisites1. Create an Event Type2. Add Availability Rules3. Check AvailabilityUsing an SDK Instead of curlNext Steps