API reference

The dlserve REST API lives at https://api.dlserve.ai/api. All endpoints require a Bearer token obtained from the dashboard (or from POST /api/auth/login).

Authoritative reference

The complete OpenAPI specification — request/response schemas, examples, validation rules, and all endpoints — is rendered as interactive Swagger UI at:

https://api.dlserve.ai/api/docs (requires sign-in)

You can also download the raw OpenAPI 3.0 JSON for use with Postman, Insomnia, or any other client:

• Production: https://api.dlserve.ai/api/docs-json
• Or via curl:

  curl https://api.dlserve.ai/api/docs-json -o dlserve.openapi.json

Authentication

Every request (except the auth endpoints below) requires a Bearer token in the Authorization header:

Authorization: Bearer <your-access-token>

Access tokens expire in 15 minutes. Use POST /api/auth/refresh with your refresh token to rotate them without re-logging in.

---

Quick reference — common endpoints

A quick orientation. The Swagger UI above is the source of truth for full schema details.

Auth — POST /api/auth/*

Endpoint	Purpose
POST /api/auth/register	Self-serve sign-up. Returns an unverified account.
POST /api/auth/login	Sign in. Returns accessToken + refreshToken.
POST /api/auth/refresh	Rotate tokens using a valid refreshToken.
POST /api/auth/verify-email	Consume the email-verification token sent on sign-up.
POST /api/auth/resend-verification	Re-send the verification email.
POST /api/auth/forgot-password	Trigger a password-reset email.
POST /api/auth/reset-password	Consume the reset token and set a new password.
POST /api/auth/logout	Revoke the current refresh token.

Channels — GET|POST /api/channels/*

A channel represents a single website where you've embedded the dlserve snippet.

Endpoint	Purpose
GET /api/channels	List all channels in your account.
POST /api/channels	Create a new channel (requires verified email).
GET /api/channels/:id	Get a single channel's details and status.
PATCH /api/channels/:id	Update channel name or settings.
DELETE /api/channels/:id	Delete a channel (irreversible).
POST /api/channels/:id/verify-install	Check that the JS snippet and service worker are detected on your site.
GET /api/channels/:id/privacy-policy	Download a pre-filled privacy policy template for the channel.
GET /api/channels/:id/snippet	Retrieve the ready-to-paste HTML/JS snippet for the channel.

Reports — GET /api/reports/*

All report endpoints accept ?from=YYYY-MM-DD&to=YYYY-MM-DD query parameters. Data comes from the ClickHouse analytics store.

Endpoint	Purpose
GET /api/reports/overview	Aggregate stats (subscribers, sends, clicks, CTR) over a date range.
GET /api/reports/by-day	Daily breakdown of the same metrics.
GET /api/reports/by-creative	Per-creative (ad) breakdown — impressions, clicks, spend.

Subscribers — GET /api/subscribers/*

Endpoint	Purpose
GET /api/subscribers	List push subscribers across your channels (paginated).
GET /api/subscribers/:id	Get details for a single subscriber.

Account — GET|PATCH /api/account

Endpoint	Purpose
GET /api/account	Get your account profile.
PATCH /api/account	Update display name or password.

---

Common request / response patterns

Pagination

List endpoints return a paginated envelope:

{
  "data": [ … ],
  "meta": {
    "total": 412,
    "page": 1,
    "perPage": 20,
    "pageCount": 21
  }
}

Use ?page=2&perPage=50 query params to navigate.

Error responses

All errors follow a consistent shape:

{
  "statusCode": 422,
  "message": ["email must be an email"],
  "error": "Unprocessable Entity"
}

Common status codes:

Code	Meaning
400	Bad request / validation failure
401	Missing or expired token
403	Forbidden (wrong role or unverified email)
404	Resource not found
422	Semantic validation error
429	Rate limited

---

For a complete list of endpoints, request bodies, and response schemas, open the interactive Swagger UI at https://api.dlserve.ai/api/docs.