Skip to content

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 every endpoint a publisher account can call — is rendered as interactive Swagger UI at:

https://api.dlserve.ai/api/docs (the page is open; the calls it makes need your token)

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

Authentication ​

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

http
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/* ​

EndpointPurpose
POST /api/auth/registerSelf-serve sign-up. Returns an unverified account.
POST /api/auth/loginSign in. Returns accessToken + refreshToken.
POST /api/auth/refreshRotate tokens using a valid refreshToken.
POST /api/auth/verify-emailConsume the email-verification token sent on sign-up.
POST /api/auth/resend-verificationRe-send the verification email.
POST /api/auth/forgot-passwordTrigger a password-reset email.
POST /api/auth/reset-passwordConsume the reset token and set a new password.
POST /api/auth/logoutEnd the session. Send the bearer, { "refreshToken": "…" } in the body, or both; the body still works after the access token has expired. Always 204.

Channels — GET|POST /api/channels/* ​

A channel represents a website where you've embedded the dlserve snippet, or an app (Android or Windows) that uses a dlserve SDK.

EndpointPurpose
GET /api/channelsList all channels in your account.
POST /api/channelsCreate a new channel (requires verified email).
GET /api/channels/:idGet a single channel's details and status.
PATCH /api/channels/:idUpdate channel name or settings.
DELETE /api/channels/:idDelete a channel (irreversible).
POST /api/channels/:id/verify-installCheck that the JS snippet and service worker are detected on your site.
GET /api/channels/:id/privacy-policyDownload the channel's pre-filled privacy policy (markdown), in the version for its type: web, Android app or Windows app.
GET /api/channels/:id/snippetRetrieve the ready-to-paste HTML/JS snippet for the channel.
POST /api/channels/:id/test-adWindows only: send the dlserve test ad to the placement's test devices (up to 10).

PATCH /api/channels/:id also takes these Windows-only fields: pullStatus (testing or live), consentMode, consentAskAfterSec (null means only when the app calls ShowConsent), pullCountries (empty means worldwide) and privacyUrl (an https:// link). They're refused on other placement kinds.

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.

EndpointPurpose
GET /api/reports/overviewAggregate stats (subscribers, sends, clicks, CTR) over a date range.
GET /api/reports/by-dayDaily breakdown of the same metrics.
GET /api/reports/by-creativePer-creative (ad) breakdown — impressions, clicks, spend.
GET /api/reports/by-platformBreakdown by kind of placement: web, Android and Windows.

Subscribers — GET /api/subscribers/* ​

EndpointPurpose
GET /api/subscribersList push subscribers across your channels (paginated).
GET /api/subscribers/:idGet details for a single subscriber.

Account — GET|PATCH /api/account ​

EndpointPurpose
GET /api/accountGet your account profile.
PATCH /api/accountUpdate display name or password.

Common request / response patterns ​

Pagination ​

List endpoints return a paginated envelope:

json
{
  "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:

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

Common status codes:

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

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