Developer API Documentation

Getting Started

The EffortList AI Developer API lets you programmatically access and manage your data from external tools, scripts, and automations. All endpoints live under a single base URL and require authentication via your API key.

Base URL

https://effortlist.io/api/v1

Available on All Plans

The Developer API is included with every EffortList AI subscription—no upgrade required. Generate your first API key in Settings → Developer.

Authentication

Every request must include an Authorization header with your API key.

API Key Authentication

Generate a persistent API key from your Settings → Developer page. Keys never expire and are ideal for server-to-server integrations, scripts, and automation platforms like Zapier.

Authorization: Bearer efai_...

bash

curl -H "Authorization: Bearer efai_your_key_here" \
  "https://effortlist.io/api/v1/folders"

Rate Limiting

To ensure stability and fair usage, the EffortList AI API enforces a rate limit of 100 requests per minute per user.

X-RateLimit-Limit

100

Requests per minute

X-RateLimit-Remaining

99

Remaining in window

X-RateLimit-Reset

1645000000

Unix reset timestamp

Rate Limit Headers

Every API response includes these headers so you can monitor your usage and avoid being throttled. When the limit is hit, the API returns a 429 Too Many Requests error.

Profile & Settings

The Profile & Settings endpoint explicitly returns the user's generic profile data as well as their local timezone, minimum notice requirements, and current working schedule. This equips external agents and systems to confidently block or schedule time on their behalf directly via API.

Public Calendar URLs

These endpoints allow you to programmatically retrieve the URLs for your public-facing schedule. Note that these URLs will only be returned if the Public Calendar feature is enabled in your settings.

Folders

Folders are the top-level organizational unit. Deleting a folder will cascade-delete all its tasks and their todos.

Tasks

Tasks belong to a folder. Deleting a task will cascade-delete all its todos.

Todos

Todos are individual items that belong to a task. They support due dates, end times, recurrence, locations, and URLs.

Appointment Smart Sync

EffortList AI automatically keeps your scheduled appointments in sync with your todos. When a guest books a time, a todo is created. If you modify that todo's due date or end time via the API, the guest will be automatically notified, and the appointment will be updated. Changes to description or location are synced silently without emailing the guest.

Booking Links

Manage your public scheduling pages programmatically. This allows you to create, update, and delete booking links that guests use to book appointments on your calendar.

Appointment Management

Manage meeting requests from guests. For links that require approval, appointments will start in a pending status.

Guest Blocking

Prevent specific email addresses from booking appointments via your public links.

Chats

Read-only access to your Omni AI chat conversations. Chats are created exclusively by the AI engine and cannot be created via the API.

Undo & Redo

Every creation, update, or deletion made via the API is recorded. You can reverse actions with undo, and re-apply them with redo. This works like a version history for your API operations.

Undo

Redo

API Key Management

Manage your API keys programmatically. You can also create and revoke keys from the Settings → Developer page in your dashboard.

Dashboard Only Management

For security reasons, creating or revoking API keys must be done manually via the Dashboard. There are no safe programmatic endpoints for these actions to prevent unauthorized key lifecycle changes.

Error Handling

All errors follow a consistent JSON shape. The HTTP status code indicates the category of error.

json

{
  "error": "Human-readable error message",
  "details": "Optional technical details (on 500 errors)",
  "hint": "Optional suggestion for fixing the issue"
}

Status	Meaning	Common Cause
200	Success	Request completed
201	Created	Resource successfully created
400	Bad Request	Missing required fields, invalid JSON, or validation failure
401	Unauthorized	Missing, expired, or invalid token/API key
403	Forbidden	Using an API key for key management endpoints
404	Not Found	Resource doesn't exist or belongs to another user
409	Conflict	Scheduling conflict or duplicate resource
429	Too Many Requests	Rate limit exceeded (100 requests / minute)
500	Server Error	Internal failure — retry or contact support

Security

Zero-Knowledge Key Storage

We store only the SHA-256 hash of your API keys. The raw key is shown once during creation and never stored. Even if our database were compromised, your keys could not be recovered.

Cross-Account Isolation

Every API request is scoped to your authenticated user ID. Cross-account access is cryptographically impossible — you can only ever access your own data unless you have a quantum computer.