API Reference

The Emberly REST API lets you upload files, shorten URLs, manage metadata, and configure custom domains from any language or tool.

Health Check

GET /api/health — works identically on cloud and self-hosted instances, no authentication required. Reports database, Redis, storage, and event-queue status, plus overall instance uptime and version:

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "2.5.1",
    "uptimeSeconds": 3600,
    "checks": {
      "database": { "status": "up", "latencyMs": 4 },
      "redis": { "status": "up", "latencyMs": 1 },
      "storage": { "status": "up", "provider": "s3", "latencyMs": 120 },
      "virusScanning": { "status": "not_configured" },
      "eventQueue": { "status": "up", "workerRunning": true }
    }
  }
}

status is ok, degraded (a non-critical check failing), or down (database unreachable — responds 503). Point an uptime monitor or reverse-proxy health check at this endpoint.

Base URL

https://embrly.ca/api

Authentication

All endpoints require a Bearer token:

Authorization: Bearer YOUR_UPLOAD_TOKEN

Get your token from Dashboard → Settings → Profile → Upload Token.

Response Format

All responses return JSON:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Human-readable error message"
}

Rate Limits

There's no general per-plan API rate limit — file uploads, listing, and most other endpoints aren't rate-limited beyond your plan's storage/upload-size caps. A small number of security-sensitive endpoints (registration, password reset, resend-verification, contact form, domain verification) have flat, IP-scoped limits regardless of plan. See the User API Reference for the full list.

Exceeding a limited endpoint's limit returns 429 Too Many Requests with a Retry-After header.

Status Codes