API Overview

Owlat exposes authenticated API endpoints under your Convex site URL.

Base URL

Use your deployment URL:

https://<your-deployment>.convex.site

Authenticated endpoints are currently under:

/api/v1/*

Authentication

Send your API key in Authorization:

Authorization: Bearer lm_live_...

API keys are created in Settings → API.

SDKs

For server-side integrations, use an official SDK instead of raw HTTP calls:

• TypeScript SDK -- @owlat/sdk-js for Node.js, Bun, and Deno
• Java SDK -- com.owlat:owlat-sdk for JVM applications (Java 11+)

Current endpoint groups

• Authentication
• Contacts API
• Lists API
• Events API
• Transactional API
• Forms API
• Webhooks
• Public Endpoints

Response format

Most endpoints return JSON in this shape:

{
  "data": {}
}

Errors use:

{
    "error": {
        "message": "Human readable message",
        "code": "error_code"
    }
}

CORS

Private API endpoints (/api/v1/*) are restricted by the ALLOWED_ORIGINS environment variable. Set it to a comma-separated list of allowed origins in the Convex dashboard:

npx convex env set ALLOWED_ORIGINS "https://app.example.com,http://localhost:3000"

Public endpoints (forms, unsubscribe, preference center) allow all origins.

Rate limits

Authenticated API requests are limited to 10 requests per second per API key.

Headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

When exceeded, responses return 429 with Retry-After.