Astrocal
Scheduling API

The calendar API that handles the bookings too

Ship scheduling in an afternoon, not a quarter. Availability, bookings, webhooks, and two-way calendar sync behind one key, with an OpenAPI 3.1 spec and MCP support for AI agents.

Get API key freeRead the docs
Check availability
# GET /v1/availability is public. No auth header required.

curl "https://api.astrocal.dev/v1/availability?\
event_type_id=evt_abc123&start=2026-04-15&end=2026-04-15&timezone=America/New_York"

# Response

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

Built for developers, not end-users

📅

Real-time availability

FreeBusy checks against connected calendars on every request. Slots update in real time, no stale data, no double-bookings.

🔗

Bookings API

Create, read, cancel, and reschedule bookings via REST. Confirmation emails and ICS attachments sent automatically.

🔔

Webhook notifications

Receive HMAC-signed payloads for booking.created, booking.cancelled, booking.rescheduled, waitlist events, and more. Automatic retry on failure.

📄

OpenAPI 3.1 spec

Auto-generated spec always in sync with the codebase. Import into Postman, generate client SDKs, or feed it to your AI coding assistant.

🌐

Google, Outlook, and CalDAV

OAuth connections for Google Calendar and Microsoft 365 / Outlook. CalDAV support for Apple Calendar, Fastmail, and self-hosted servers. Events written back automatically.

🤖

MCP for AI agents

The @astrocal/mcp-server npm package gives Claude, Cursor, and custom agents the ability to check availability and create bookings natively.

Core endpoints

Four endpoints cover 90% of scheduling workflows. Full reference in the docs.

GET/v1/availabilityFetch open time slots for an event type and date range (public, no auth)
Response
{
  "event_type_id": "evt_abc123",
  "timezone": "America/New_York",
  "slots": [
    {
      "start_time": "2026-04-15T09:00:00Z",
      "end_time": "2026-04-15T09:30:00Z"
    },
    {
      "start_time": "2026-04-15T10:00:00Z",
      "end_time": "2026-04-15T10:30:00Z"
    },
    {
      "start_time": "2026-04-15T14:00:00Z",
      "end_time": "2026-04-15T14:30:00Z"
    }
  ]
}
POST/v1/bookingsCreate a confirmed booking
Request
{
  "event_type_id": "evt_abc123",
  "start_time": "2026-04-15T14:00:00Z",
  "invitee_name": "Jo Smith",
  "invitee_email": "jo@acme.com",
  "invitee_timezone": "America/New_York",
  "metadata": {
    "source": "website"
  }
}
Response
{
  "id": "bk_7f3a9c2e",
  "status": "confirmed",
  "start_time": "2026-04-15T14:00:00Z",
  "end_time": "2026-04-15T14:30:00Z",
  "invitee_name": "Jo Smith",
  "invitee_email": "jo@acme.com",
  "created_at": "2026-04-10T12:00:00Z"
}
POST/v1/bookings/{id}/cancelCancel an existing booking (idempotent, safe to retry)
Request
{
  "reason": "Customer requested cancellation"
}
Response
{
  "id": "bk_7f3a9c2e",
  "status": "cancelled",
  "cancelled_at": "2026-04-12T08:30:00Z"
}
POST/v1/webhooksRegister a webhook endpoint
Request
{
  "url": "https://your-app.com/webhooks/astrocal",
  "events": [
    "booking.created",
    "booking.cancelled",
    "booking.rescheduled"
  ]
}
Response
{
  "id": "wh_e4b2d1a8",
  "url": "https://your-app.com/webhooks/astrocal",
  "events": [
    "booking.created",
    "booking.cancelled",
    "booking.rescheduled"
  ],
  "secret": "whsec_...",
  "created_at": "2026-04-10T12:05:00Z"
}

Frequently asked questions

Bearer token authentication with API keys. Generate keys from the dashboard: live keys (ac_live_...) for production, test keys (ac_test_...) for sandbox. Authenticated requests use the Authorization: Bearer ac_live_... header. The availability endpoint is public and needs no key.
Yes. Free plans allow 30 requests per minute and 200 per day. Paid plans scale to 2,000 RPM and 50,000 daily. Rate limit headers are included in every response so you can build backoff logic.
A PostgreSQL EXCLUDE constraint enforces non-overlapping time slots at the database level. Even under concurrent load, two bookings cannot occupy the same slot. The database rejects the second one.
Absolutely. The API is the product. The widget is optional. Build your own booking UI, integrate scheduling into a CLI tool, or let an AI agent handle it entirely through the MCP server.
Google Calendar, Microsoft 365 / Outlook, and any CalDAV-compatible calendar (Apple Calendar, Fastmail, Nextcloud). All use OAuth for secure connection. FreeBusy checks run on every availability request.
Yes. The spec is auto-generated from the codebase and always up to date. Fetch it at /v1/openapi.json or download it from the docs. Import into Postman, Insomnia, or use it to generate typed clients.

Get your API key in 30 seconds

Free plan includes full API access, calendar sync, and 10 bookings per month. No credit card required.

Get API key freeRead the docs