API Reference

Use the Emberly REST API to upload files, shorten links and manage your account.

Every Emberly instance has the same REST API, whether it's embrly.ca or your own server. Anything you can do in the dashboard for your own files, links and account, you can do through the API.

Files

Upload, list, update and delete files, including large uploads.

Short Links

Create, list and delete short links.

Account

Profile, API keys, upload tokens, sessions and 2FA.

Device Sign-In

Let a desktop app sign in through the browser.

Analytics

Usage, storage and top files.

Custom Domains

Add and verify your own upload domains (embrly.ca).

Discovery

Squads, profiles and opportunities (embrly.ca).

Admin

Endpoints behind the admin panel.

Base URL

Use your instance's address. For embrly.ca:

https://embrly.ca/api

Authentication

Send a key in the Authorization header:

curl https://embrly.ca/api/files \
  -H "Authorization: Bearer ebk_..."

Credential	Where to get it	Use it for
API key (`ebk_...`)	Profile → API, or `POST /api/profile/api-keys`	Scripts and apps. You can have up to 10, each with a name, and revoke them one by one.
Upload token	Profile → Uploads	ShareX, Flameshot and other upload tools. You have one, and resetting it breaks every tool using it.
Browser session	Signing in to the website	The dashboard itself. Not meant for scripts.

API keys and upload tokens both act as your whole account, so keep them secret. Prefer API keys for anything new: you can see when each was last used and revoke one without affecting the others.

Desktop apps should use device sign-in instead of asking for a password.

Responses

Successful responses are JSON with success: true and the result in data:

{
  "success": true,
  "data": { "id": "clx...", "url": "https://embrly.ca/aB3dE/photo.png" }
}

Errors return success: false and a message:

{
  "success": false,
  "error": "File not found"
}

Lists that support paging add a pagination object:

{
  "success": true,
  "data": [ ... ],
  "pagination": { "total": 120, "pageCount": 5, "page": 1, "limit": 24 }
}

A few older endpoints return the object directly, without the success/data wrapper. Each page says so where it applies.

Status Codes

Code	Meaning
`200`	Success
`201`	Created
`202`	Accepted, still in progress (used while polling)
`204`	Success, no content
`400`	The request was invalid. The `error` field says why.
`401`	Missing or invalid credentials, or a wrong file password
`403`	Signed in, but not allowed to do this
`404`	Not found, or private and not yours
`413`	File too large for your upload limit
`429`	Rate limited. Wait and try again.
`500`	Server error

Rate Limits

Uploads and most endpoints aren't rate limited; storage quotas and upload size limits apply instead. These endpoints are limited per IP address:

Endpoint	Limit
`POST /api/auth/register`	5 per minute
`POST /api/auth/password/forgot`	1 per 10 minutes
`POST /api/auth/password/reset`	5 per 10 minutes
`POST /api/auth/resend-verification`	3 per 10 minutes
`POST /api/device/code`	10 per 10 minutes

Health Check

GET /api/health needs no authentication. It reports whether the database, Redis, storage and background jobs are working, and returns 503 if the database is down. See Health Checks.

Server Information

GET /api/instance needs no authentication. Apps use it to adapt to the server they're connected to:

{
  "success": true,
  "data": {
    "name": "Emberly",
    "version": "3.1.0",
    "cloud": true,
    "billingEnabled": false,
    "features": {
      "customDomains": true,
      "squads": true,
      "discovery": true,
      "deviceSignIn": true
    }
  }
}