API Reference

Trelay exposes a REST API for links, folders, stats, preview, and import/export. All endpoints except health checks and redirects require authentication via API key or JWT.

Base URL

Use your server URL as the base, e.g. http://localhost:8080 or https://links.example.com.

Authentication

Use one of:

• API key — Send header X-API-Key: YOUR_API_KEY on every request.
• JWT — Login via POST /api/v1/auth/login with {"api_key":"YOUR_API_KEY"}, then send Authorization: Bearer <token> on subsequent requests.

Redirects (GET /{slug}) and GET /healthz do not require auth.

Endpoints

Health

Method	Endpoint	Description
GET	/healthz	Health check. Returns {"status":"ok"}.

Auth

Method	Endpoint	Description
POST	/api/v1/auth/login	Login with API key. Body: {"api_key":"YOUR_API_KEY"}. Returns token and expires_at.

Links

Method	Endpoint	Description
POST	/api/v1/links	Create link. Body: url (required), slug, domain, password, ttl_hours, tags, folder_id, is_one_time.
GET	/api/v1/links	List links. Query: search, folder_id, limit, offset, include_deleted, only_deleted, created_after, created_before.
GET	/api/v1/links/{slug}	Get link by slug.
PATCH	/api/v1/links/{slug}	Update link. Body: url, password, ttl_hours, tags, folder_id.
DELETE	/api/v1/links/{slug}	Delete link (soft-delete). Query: permanent=true for hard delete.
POST	/api/v1/links/{slug}/restore	Restore a soft-deleted link.
DELETE	/api/v1/links	Bulk delete. Body: {"slugs":["a","b"]}, optional permanent.

Redirect (no auth)

Method	Endpoint	Description
GET	/{slug}	Redirect to original URL. Query: password if link is password-protected.

Folders

Method	Endpoint	Description
GET	/api/v1/folders	List folders.
POST	/api/v1/folders	Create folder. Body: name (required), parent_id.
GET	/api/v1/folders/{id}	Get folder by ID.
DELETE	/api/v1/folders/{id}	Delete folder.

Stats

Method	Endpoint	Description
GET	/api/v1/stats/{slug}	Get click stats. Query: period, export=csv or export=json for file download.
GET	/api/v1/stats/{slug}/daily	Daily click breakdown.
GET	/api/v1/stats/{slug}/referrers	Top referrers.

Preview

Method	Endpoint	Description
GET	/api/v1/preview?url=	Fetch Open Graph metadata for a URL. Returns title, description, image_url, fetched_at.

Import & Export

See Import & Export for CSV/JSON import and export endpoints.

Response format

Success responses are JSON with success: true and data containing the result. List endpoints may include meta with total, limit, offset.

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

Errors return appropriate HTTP status and a body like:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "url is required",
    "field": "url"
  }
}

OpenAPI spec

The full OpenAPI 3.0 spec is in the repo at api/openapi.yaml. You can use it with Swagger UI, Postman, or code generators.