API Documentation

Use these endpoints to manage your AI agent's calendar programmatically.

Authentication

Agent API endpoints use Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer ak_your_api_key_here

API keys are shown once during creation. Store them securely — they cannot be retrieved later. If lost, you can regenerate a key from the agent detail page (this revokes the old key).

Events

Create, read, update, and delete calendar events for your agent.

List Events

Get all events for your agent's calendar, with optional filtering.

GET/api/v1/events

Returns events in the agent's calendar. Supports filtering by date range and pagination.

Auth:Bearer API Key

Response

// Query params (all optional):
//   start_after  - ISO 8601 datetime
//   start_before - ISO 8601 datetime
//   limit        - default 100, max 500
//   offset       - default 0

{
  "events": [
    {
      "id": "uuid",
      "title": "Team Standup",
      "start": "2025-01-15T09:00:00Z",
      "end": "2025-01-15T09:30:00Z",
      "description": "Daily sync",
      "location": "Zoom",
      "allDay": false,
      "rrule": null
    }
  ]
}

Get Event

Retrieve a single event by ID.

GET/api/v1/events/:id

Returns a single event from the agent's calendar.

Auth:Bearer API Key

Response

{
  "event": {
    "id": "uuid",
    "title": "Team Standup",
    "start": "2025-01-15T09:00:00Z",
    "end": "2025-01-15T09:30:00Z",
    "description": "Daily sync",
    "location": "Zoom",
    "allDay": false,
    "rrule": null
  }
}

Create Event

Add a new event to the calendar.

POST/api/v1/events

Creates a new calendar event.

Auth:Bearer API Key

Request Body

{
  "title (required)": "string",
  "start (required)": "ISO 8601 datetime",
  "end (required)": "ISO 8601 datetime",
  "description": "string (optional)",
  "location": "string (optional)",
  "allDay": "boolean (optional, default false)",
  "rrule": "string (optional, iCal RRULE format)"
}

Response

{
  "event": {
    "id": "uuid",
    "title": "Team Standup",
    "start": "2025-01-15T09:00:00Z",
    "end": "2025-01-15T09:30:00Z",
    ...
  }
}

Update Event

Modify an existing event (partial update).

PUT/api/v1/events/:id

Updates one or more fields of an event.

Auth:Bearer API Key

Request Body

{
  "title": "string (optional)",
  "start": "ISO 8601 datetime (optional)",
  "end": "ISO 8601 datetime (optional)",
  "description": "string (optional)",
  "location": "string (optional)",
  "allDay": "boolean (optional)",
  "rrule": "string (optional)"
}

Response

{ "event": { ... } }

Delete Event

Remove an event from the calendar.

DELETE/api/v1/events/:id

Permanently deletes the event.

Auth:Bearer API Key

Response

{ "deleted": true }

Documents

Store and retrieve markdown documents for your agent.

List Documents

Get all documents for your agent.

GET/api/v1/docs

Returns documents belonging to the authenticated agent. Supports pagination.

Auth:Bearer API Key

Response

// Query params (all optional):
//   limit  - default 100, max 500
//   offset - default 0

{
  "documents": [
    {
      "id": "uuid",
      "agentId": "uuid",
      "title": "Meeting Notes",
      "content": "# Notes\n...",
      "createdAt": "2025-01-15T09:00:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ]
}

Get Document

Retrieve a single document by ID.

GET/api/v1/docs/:id

Returns a single document.

Auth:Bearer API Key

Response

{
  "document": {
    "id": "uuid",
    "agentId": "uuid",
    "title": "Meeting Notes",
    "content": "# Notes\n...",
    "createdAt": "2025-01-15T09:00:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}

Create Document

Create a new document.

POST/api/v1/docs

Creates a new document.

Auth:Bearer API Key

Request Body

{
  "title (required)": "string",
  "content": "string (optional, markdown)"
}

Response

{ "document": { ... } }

Update Document

Modify an existing document (partial update).

PUT/api/v1/docs/:id

Updates one or more fields of a document.

Auth:Bearer API Key

Request Body

{
  "title": "string (optional)",
  "content": "string (optional, markdown)"
}

Response

{ "document": { ... } }

Delete Document

Permanently remove a document.

DELETE/api/v1/docs/:id

Permanently deletes the document.

Auth:Bearer API Key

Response

{ "deleted": true }

Calendar Subscriptions

Share your agent's calendar via iCalendar (ICS) subscriptions. Subscribers can import the URL into Google Calendar, Apple Calendar, Outlook, etc.

iCalendar Feed

Public endpoint for calendar apps to fetch events.

GET/api/cal/:agentId/:token.ics

Returns an iCalendar feed. No auth header needed — the token in the URL acts as authentication.

Auth:Token in URL

Response

BEGIN:VCALENDAR
PRODID:-//AgentWorkspace//Calendar//EN
METHOD:PUBLISH
...
END:VCALENDAR

Error Responses

All error responses follow this format:

// Simple error
{ "error": "Unauthorized" }

// Validation error
{
  "error": "Validation failed",
  "issues": [
    { "path": "title", "message": "Title is required" },
    { "path": "start", "message": "start must be an ISO 8601 datetime" }
  ]
}

400Bad request / validation error

401Missing or invalid API key

403Not authorized to access this resource

404Resource not found

Security →Known Issues →