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"

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.

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
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.