API Overview

Design Principles

1. REST-inspired: Resources are nouns, HTTP methods are verbs
2. JSON everywhere: All request/response bodies use JSON (except CSV exports)
3. Auth first: Every protected endpoint checks authentication before processing
4. Consistent errors: All errors return { "error": "message" } with appropriate status codes

Base URL

https://lydaro.app/api

Authentication

All endpoints except webhooks require a valid Supabase session. The session cookie is set automatically when using the Lydaro web app.

Unauthenticated requests to protected endpoints return 401 Unauthorized.

Response Format

Success

{
  "data": { ... }
}

Error

{
  "error": "Human-readable error message"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request (missing/invalid parameters)
401	Unauthenticated
403	Forbidden (insufficient permissions)
404	Not found
402	Payment required (usage limit exceeded)
500	Server error

Rate Limiting

AI endpoints are rate-limited per organisation using Upstash Redis. Other endpoints are not currently rate-limited.