CalDave API ← Status

Calendar-as-a-service for AI agents. Base URL: https://caldave.ai

Endpoints

Auth
Calendars
Events
Feeds & Webhooks

Authentication

Most endpoints require a Bearer token. Include it in every request:

Authorization: Bearer sk_live_your_api_key_here

Exceptions: POST /agents (no auth), GET /feeds (token in query param), and POST /inbound (token in URL path).

Agent Provisioning

POST /agents No auth

Create a new agent identity. Returns credentials you must save — the API key is shown once.

Example
curl -s -X POST https://caldave.ai/agents
Response
{
  "agent_id": "agt_x7y8z9AbCd",
  "api_key": "sk_live_abc123...",
  "message": "Store these credentials securely. The API key will not be shown again."
}

Calendars

POST /calendars Bearer token

Create a new calendar for the authenticated agent.

Body parameters
name requiredCalendar display name
timezone optionalIANA timezone (default: UTC)
agentmail_api_key optionalAgentMail API key for fetching inbound email attachments
Example
curl -s -X POST https://caldave.ai/calendars \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Work Schedule", "timezone": "America/Denver"}'
Response
{
  "calendar_id": "cal_a1b2c3XyZ",
  "name": "Work Schedule",
  "timezone": "America/Denver",
  "email": "cal-a1b2c3XyZ@caldave.ai",
  "ical_feed_url": "https://caldave.ai/feeds/cal_a1b2c3XyZ.ics?token=feed_...",
  "feed_token": "feed_...",
  "inbound_webhook_url": "https://caldave.ai/inbound/inb_...",
  "message": "This calendar can receive invites at cal-a1b2c3XyZ@caldave.ai. ..."
}
GET /calendars Bearer token

List all calendars for the authenticated agent.

Example
curl -s https://caldave.ai/calendars \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /calendars/:id Bearer token

Get a single calendar by ID.

Example
curl -s https://caldave.ai/calendars/cal_a1b2c3XyZ \
  -H "Authorization: Bearer YOUR_API_KEY"
PATCH /calendars/:id Bearer token

Update calendar settings. All fields are optional.

Body parameters
nameCalendar display name
timezoneIANA timezone
webhook_urlURL to receive event notifications
webhook_secretHMAC secret for webhook signatures
webhook_offsetsArray of offsets, e.g. ["-5m", "-1m"]
agentmail_api_keyAgentMail API key for this calendar
Example
curl -s -X PATCH https://caldave.ai/calendars/cal_a1b2c3XyZ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Updated Name", "timezone": "America/New_York"}'
DELETE /calendars/:id Bearer token

Delete a calendar and all its events. Returns 204 on success.

Example
curl -s -X DELETE https://caldave.ai/calendars/cal_a1b2c3XyZ \
  -H "Authorization: Bearer YOUR_API_KEY"

Events

POST /calendars/:id/events Bearer token

Create an event on a calendar. Supports one-off and recurring events.

Body parameters
title requiredEvent title/summary
start requiredISO 8601 datetime with timezone
end requiredISO 8601 datetime with timezone
description optionalFree text (max 64KB)
metadata optionalStructured JSON payload (max 16KB)
location optionalFree text or URL
status optionalconfirmed (default), tentative, cancelled
attendees optionalArray of email addresses
recurrence optionalRFC 5545 RRULE string (e.g. FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR)
Example — one-off event
curl -s -X POST https://caldave.ai/calendars/CAL_ID/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "Team standup",
    "start": "2025-03-01T09:00:00-07:00",
    "end": "2025-03-01T09:15:00-07:00",
    "location": "https://meet.google.com/abc-defg-hij"
  }'
Example — recurring event
curl -s -X POST https://caldave.ai/calendars/CAL_ID/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "Daily weather email",
    "start": "2025-03-01T08:00:00-07:00",
    "end": "2025-03-01T08:05:00-07:00",
    "metadata": {"action": "send_email", "prompt": "Send weather forecast"},
    "recurrence": "FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"
  }'
Recurring events are expanded into individual instances for the next 90 days. The response includes instances_created count.
GET /calendars/:id/events Bearer token

List events with optional filters. Returns expanded recurring event instances.

Query parameters
startFilter events starting after this datetime
endFilter events starting before this datetime
statusFilter by status (confirmed, tentative, cancelled)
limitMax results (default 50, max 200)
offsetPagination offset (default 0)
Example
curl -s "https://caldave.ai/calendars/CAL_ID/events?start=2025-03-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /calendars/:id/events/:event_id Bearer token

Get a single event by ID.

Example
curl -s https://caldave.ai/calendars/CAL_ID/events/evt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
PATCH /calendars/:id/events/:event_id Bearer token

Update an event. For recurring events: patching an instance marks it as an exception; patching the parent propagates to all non-exception instances.

Body parameters
titleEvent title
startNew start time
endNew end time
descriptionFree text
metadataJSON payload
locationLocation
statusconfirmed, tentative, cancelled
attendeesArray of email addresses
recurrenceUpdated RRULE (parent only — triggers rematerialization)
Example
curl -s -X PATCH https://caldave.ai/calendars/CAL_ID/events/evt_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"title": "Updated title", "location": "Room 42"}'
DELETE /calendars/:id/events/:event_id Bearer token

Delete an event. For recurring event instances, use the mode query parameter.

Query parameters
modesingle — cancel this instance only (default)
future — cancel this and all future instances
all — delete entire series
Example
curl -s -X DELETE "https://caldave.ai/calendars/CAL_ID/events/evt_abc123?mode=single" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /calendars/:id/upcoming Bearer token

Get the next N events starting from now. Designed for agent polling.

Query parameters
limitNumber of events to return (default 5, max 50)
Example
curl -s https://caldave.ai/calendars/CAL_ID/upcoming \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "events": [...],
  "next_event_starts_in": "PT14M30S"
}
next_event_starts_in is an ISO 8601 duration showing how long until the next event. Useful for setting poll intervals.
GET /calendars/:id/view Bearer token

Plain text table of upcoming events. Useful for quick inspection via curl or agent debugging.

Query parameters
limitNumber of events to show (default 10, max 50)
Example
curl -s https://caldave.ai/calendars/CAL_ID/view \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (text/plain)
Work (cal_xxx)  tz: America/Denver
-----------------------------------------
TITLE          START                 ...
-----------------------------------------
Daily standup  2026-02-13 16:00:00Z  ...
-----------------------------------------
1 event(s)
POST /calendars/:id/events/:event_id/respond Bearer token

Accept or decline an inbound calendar invite.

Body parameters
response requiredaccepted, declined, or tentative
Example
curl -s -X POST https://caldave.ai/calendars/CAL_ID/events/evt_abc123/respond \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"response": "accepted"}'

iCal Feed

GET /feeds/:calendar_id.ics Token in query param

Read-only iCalendar feed. Subscribe to this URL from Google Calendar, Apple Calendar, or any iCal-compatible app. The feed_token is returned when you create a calendar.

Example
curl -s "https://caldave.ai/feeds/cal_a1b2c3XyZ.ics?token=feed_xyz789"
Add this URL to Google Calendar via "Other calendars" → "From URL". Events appear as read-only.

Inbound Email Webhook

POST /inbound/:token Token in URL

Receives forwarded emails containing .ics calendar invite attachments. Each calendar has a unique webhook URL (returned at creation as inbound_webhook_url). Supports Postmark and AgentMail providers.

How it works
REQUEST / PUBLISHCreates a new event (or updates if ical_uid matches). Status set to tentative.
CANCELSets matching event status to cancelled
Postmark: Set your inbound domain to forward to the webhook URL. Attachments are decoded from base64 inline.

AgentMail: Set the webhook URL in AgentMail's inbox settings. CalDave fetches .ics attachments via the AgentMail API using the calendar's agentmail_api_key.
Response (always 200)
{ "status": "created", "event_id": "evt_xxx" }
{ "status": "updated", "event_id": "evt_xxx" }
{ "status": "cancelled", "event_id": "evt_xxx" }
{ "status": "ignored", "reason": "..." }

Quick Start

Get up and running in three steps:

1. Create an agent
curl -s -X POST https://caldave.ai/agents

Save the agent_id and api_key from the response.

2. Create a calendar
curl -s -X POST https://caldave.ai/calendars \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "My Calendar", "timezone": "America/Denver"}'

Save the calendar_id, email, and feed URLs from the response.

3. Create an event
curl -s -X POST https://caldave.ai/calendars/YOUR_CAL_ID/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "My first event",
    "start": "2025-03-01T10:00:00-07:00",
    "end": "2025-03-01T11:00:00-07:00"
  }'