Developers
API Overview Both
The TapTidy REST API lets you manage tasks, projects, routines, and household data programmatically. All endpoints live under a single versioned path prefix and return JSON.
Base URL
https://api.taptidy.app/api/v1/Self-hosted instances use the configured hostname in place of api.taptidy.app. The API version is embedded in the path (/api/v1/); breaking changes will introduce a new version prefix.
Content Type
All request bodies must use Content-Type: application/json (max 10 MB). Responses are application/json unless otherwise noted. The sync change-log endpoint can stream application/x-ndjson.
Authentication
Most endpoints require authentication. The API supports several credential types:
- Session cookie — issued on browser login, used by the web app.
- Personal Access Token (PAT) —
Authorization: Bearer taptidy_pat_<id>.<secret>. Recommended for scripts and integrations. - App Password —
Authorization: Basic base64(email:<appPasswordId>.<secret>). Used by CalDAV clients and tools expecting HTTP Basic Auth.
PATs and App Passwords are Pro features. See Authentication for token generation, scopes, and best practices.
Pagination
List endpoints use offset/limit or cursor-based pagination depending on the resource:
| Pattern | Parameters | Used by |
|---|---|---|
| Offset/limit | limit (default 50, max 100), offset (default 0) | Tasks, focus sessions, economy ledger |
| Cursor | limit, cursor (UUID or ISO date) | Household tasks, routines timeline, audit receipts |
| Monotonic sequence | since (decimal string), limit | Sync change log |
All paginated responses include a hasMore boolean. Cursor-based responses include nextCursor when more pages exist. For stable task pagination across sync cycles, pass orderBy=id.
Rate Limits
Requests are rate-limited per IP and per authenticated user. Exceeding limits returns HTTP 429 with RATE_LIMIT_EXCEEDED and standard RateLimit-* headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset).
| Scope | Free | Pro | Window |
|---|---|---|---|
| General API | 500 req | 1,500 req | 1 minute |
| Auth endpoints | 5 req per IP+email | 15 minutes | |
| Sensitive mutations | 5 req per user+route | 1 hour | |
See API Errors for the full error envelope and header format.
Idempotency
Mutating requests to /tasks, /projects, and /tags support the Idempotency-Key header (UUID). Sending the same key replays the original response (indicated by Idempotent-Replay: true) instead of creating duplicates. Concurrent requests with the same key receive HTTP 409 with DUPLICATE_IN_PROGRESS and a Retry-After header.
Correlation IDs
Every response includes a X-Request-Id header. Include this value in support requests to help trace issues.
What Next
- Authentication — token generation, scopes, and credential management.
- API Errors — error envelope, status codes, and rate-limit headers.
- Requests & Responses — date formats, identifiers, and request conventions.
- API Reference — full OpenAPI specification.