Astrocal
Calendar API

One API for availability, bookings, and calendar sync

Ship scheduling in hours, not months. OpenAPI 3.1 spec, snake_case JSON, cursor pagination, and webhook notifications. All behind a single REST API.

Get API key freeRead the docs
Check availability
curl https://api.astrocal.dev/v1/availability \
-H "Authorization: Bearer sk_live_..." \
-d "event_type_id=evt_abc123&date=2026-04-15"

# Response

{
"data": [
{ "start": "2026-04-15T09:00:00Z", "end": "2026-04-15T09:30:00Z" },
{ "start": "2026-04-15T10:00:00Z", "end": "2026-04-15T10:30:00Z" },
{ "start": "2026-04-15T14:00:00Z", "end": "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 CRUD

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

🔔

Webhook notifications

Receive HMAC-signed payloads for booking.created, booking.cancelled, and booking.rescheduled events. 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
Response
{
  "data": [
    {
      "start": "2026-04-15T09:00:00Z",
      "end": "2026-04-15T09:30:00Z"
    },
    {
      "start": "2026-04-15T10:00:00Z",
      "end": "2026-04-15T10:30:00Z"
    },
    {
      "start": "2026-04-15T14:00:00Z",
      "end": "2026-04-15T14:30:00Z"
    }
  ]
}
POST/v1/bookingsCreate a confirmed booking
Request
{
  "event_type_id": "evt_abc123",
  "start": "2026-04-15T14:00:00Z",
  "invitee": {
    "name": "Jo Smith",
    "email": "jo@acme.com"
  },
  "metadata": {
    "source": "website"
  }
}
Response
{
  "id": "bk_7f3a9c2e",
  "status": "confirmed",
  "start": "2026-04-15T14:00:00Z",
  "end": "2026-04-15T14:30:00Z",
  "invitee": {
    "name": "Jo Smith",
    "email": "jo@acme.com"
  },
  "created_at": "2026-04-10T12:00:00Z"
}
DELETE/v1/bookings/{id}Cancel an existing booking
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 for production, test keys for sandbox. All requests require the Authorization: Bearer sk_live_... header.
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, Google Calendar sync, and 10 bookings per month. No credit card required.

Get API key freeRead the docs