Build on your stream.

Quick start

Use the API from your own server or personal app. Endpoints use JSON and require the appropriate key permissions. Activity is read-only; bot settings can be changed with bot:write. The base URL is https://donolink.nl/api/v1.

1. Go to Settings → Developer → API keys. Name your integration and choose an expiry date.
2. Copy the key once and store it as DONOLINK_API_KEY in your server secret configuration.
3. Make your first request. Without filters, you receive up to 50 events, newest first.

curl 'https://donolink.nl/api/v1/activity?limit=50' \
  -H "Authorization: Bearer $DONOLINK_API_KEY"

Example response

{
  "data": [
    {
      "id": "evt_abcdefghijklmno",
      "type": "subscription",
      "platform": "twitch",
      "occurred_at": "2026-09-07T12:00:00.000Z",
      "recorded_at": "2026-09-07T12:00:00.000Z",
      "actor": {
        "name": "StreamFan"
      },
      "message": null,
      "value": 3,
      "unit": "months",
      "currency": null,
      "refunded_amount_cents": null
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": "OPAQUE_CURSOR"
  }
}

Authentication

Send your key in the Authorization header with every request. A session cookie, query parameter or overlay token does not grant access to this API.

Authorization: Bearer dl_live_YOUR_SECRET_KEY

Choose a validity of 30, 90 or 365 days. You can have up to 10 active keys and create one key per minute. DonoLink stores only a SHA-256 hash; the full key is visible only immediately after creation.

Use a separate key per integration. To rotate, create a new key, update your app, then revoke the old one. A revoked or expired key stops working on the next request.

Choose activity:read, bot:read and/or bot:write when creating a key. Permissions are independent; existing keys retain activity:read only. Each key is bound to your account and grants no payment or platform administration rights. Multi-customer OAuth is not available yet.

Endpoints

Check which streamer your key belongs to and when it expires. Only the public profile, scope and key metadata are returned.

{
  "data": {
    "id": "abcdefghijklmno",
    "username": "streamer",
    "display_name": "Streamer",
    "scopes": [
      "activity:read"
    ],
    "key": {
      "prefix": "dl_live_123456789",
      "expires_at": "2026-12-06 12:00:00.000Z"
    }
  }
}

Read the combined feed of DonoLink donations and stored platform events. The account is determined exclusively from the API key.

Unknown or repeated parameters return HTTP 400. Do not put an account ID, key or PocketBase filter in the URL.

Requires bot:read. Returns data containing revision and config for your bot. No query parameters. Configuration includes commands, timers, filters, regulars and builtins. Treat response templates as confidential data.

Requires bot:write. Send the complete config and last-read revision as a JSON object. Success returns data with the new revision and config. On 409 revision_conflict, read again and reconcile newer changes before saving. Do not send an owner ID; the key determines the account.

{
  "revision": 7,
  "config": {
    "version": 1,
    "enabled": true,
    "commands": [
      {
        "id": "cmd_socials",
        "name": "!socials",
        "message": "Follow the stream at {channel}!",
        "enabled": true,
        "role": "everyone",
        "cooldownSeconds": 30,
        "alias": ""
      }
    ],
    "timers": [],
    "filters": {
      "words": {
        "enabled": true,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 1,
        "minLength": 0
      },
      "caps": {
        "enabled": false,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 50,
        "minLength": 10
      },
      "emotes": {
        "enabled": false,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 20,
        "minLength": 10
      },
      "links": {
        "enabled": true,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 1,
        "minLength": 10
      },
      "symbols": {
        "enabled": false,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 30,
        "minLength": 10
      },
      "repetitions": {
        "enabled": false,
        "exemptRole": "moderator",
        "timeoutSeconds": 600,
        "silent": false,
        "message": "",
        "threshold": 10,
        "minLength": 10
      }
    },
    "blockedWords": [
      "exampleword"
    ],
    "allowedHosts": [
      "youtube.com"
    ]
  }
}

Use application/json and UTF-8, at most 2,000,000 bytes within ten seconds. Invalid config returns 422; missing permission returns 403. OpenAPI specifies all fields and bounds. After an uncertain write result, read and compare the configuration; never blindly overwrite a newer revision.

GET requires bot:read and returns data with revision and state: queue, playlist, settings and playback state. POST requires bot:write: send operationKey (16 to 100 letters/digits/_/-), revision and action. Actions: request/playlist-add with query, settings, playlist-remove, remove, promote, move (positions start at 1), volume, seek, play, pause, skip and clear. See OpenAPI for all fields. After an uncertain response, retry the identical body; the action applies once. On music_revision_conflict read again and reconcile; use a new operationKey for a changed action. Maximum 16,000 bytes within 10 seconds; no query parameters or owner fields. Playback requires an active dashboard player. YouTube search requires server configuration; SoundCloud search requires a client ID and client secret on the server.

{
  "operationKey": "42eed350-2ab8-46ea-8ae4-c02dfe296f9e",
  "revision": 3,
  "action": {
    "kind": "request",
    "query": "https://www.youtube.com/watch?v=abcdefghijk"
  }
}

Event format

Each event has a stable id prefixed with don_ or evt_. Use this id to prevent duplicate processing after a retry.

actor.name is the stored display name or null. message is text or null. occurred_at is the donation date; for platform events only the storage time is known. recorded_at always contains the storage time and determines pagination. All timestamps are UTC ISO 8601.

For donation, value is the original amount in integer cents and currency is the currency. refunded_amount_cents contains the refunded amount for DonoLink, otherwise null. Donations with status paid are shown, including imported history with the import source as platform. Fully refunded and disputed donations are excluded. This is an activity feed, not a financial ledger.

Platform events are available to the extent DonoLink received and stored them through an active connection. History from before the connection is not fetched from the platform. There is no guaranteed retention period; deleted records cannot be retrieved. Test alerts are not included.

History & live feed

For an export, use order=asc with fixed since and until boundaries. Process data and request the next page using next_cursor while has_more is true. There is no limit on historical page count, but request limits apply.

An empty page preserves your existing cursor. With no previous cursor and no events, next_cursor is null. Cursors contain no API key, but treat them as opaque values. After changing filters, start without a cursor.

For your IRL app, use order=asc, a fixed since and no until. Save the cursor only after processing events. Poll about every 5 seconds; when has_more is true, continue directly to the next page. v1 has no WebSocket or webhook endpoint.

// Node.js: run on your server. Keep the key out of frontend bundles.
const base = new URL('https://donolink.nl/api/v1/activity');
base.searchParams.set('order', 'asc');
base.searchParams.set('limit', '100');
// Persist both this fixed starting point and the returned cursor.
base.searchParams.set('since', '2026-09-07T00:00:00Z');
let cursor = await loadCheckpoint();
for (;;) {
  const url = new URL(base);
  if (cursor) url.searchParams.set('cursor', cursor);
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + process.env.DONOLINK_API_KEY },
    signal: AbortSignal.timeout(15000)
  }).catch(() => null);
  if (!response || response.status === 429 || response.status >= 500) {
    const seconds = Number(response?.headers.get('Retry-After') || 60);
    await new Promise(r => setTimeout(r, seconds * 1000));
    continue;
  }
  if (!response.ok) throw new Error('DonoLink API: ' + response.status);
  const page = await response.json();
  // Implement these storage functions in your app.
  // Process idempotently by event.id, then save the checkpoint.
  for (const event of page.data) await processOnce(event.id, event);
  if (page.pagination.next_cursor) {
    cursor = page.pagination.next_cursor;
    await saveCheckpoint(cursor);
  }
  if (!page.pagination.has_more)
    await new Promise(r => setTimeout(r, 5000));
}

The feed reads current stored records and is not an immutable snapshot or a guaranteed exactly-once event bus. Payment status changes can remove previously visible records. Use idempotent processing, retries and, when needed, overlapping reads for recovery.

Limits & errors

Maximum 120 requests per 60 seconds per account, shared by all keys. There is also a limit of 300 requests per 60 seconds per IP address. HTTP 429 and 503 include Retry-After: 60. Wait that long and retry with the same cursor.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid, expired or revoked.",
    "request_id": "request-uuid"
  }
}

Every response has X-Request-Id; error responses also include error.request_id. Include this ID and the time when contacting support. Never share your key, Authorization header or full request logs. Use GET for data. HEAD and OPTIONS are available for HTTP checks; write methods return 405.

Secure integration

Use HTTPS. Never put keys in URLs, Git, browser code, localStorage, analytics or log files. API responses use Cache-Control: private, no-store. The API does not provide cross-origin browser access.

In a personal native app, enter your own key and store it in Keychain or Android Keystore. For apps serving others, use a backend with isolated secrets per user. Never embed a shared key in the app binary.

The API returns only display names, messages, event values and limited profile details. Email addresses, payment methods, Stripe IDs, platform tokens and administration settings are not shared. Treat names and messages as personal data and store only what your integration needs.

If a key leaks, revoke it immediately under Settings → Developer and create a replacement. Revoked and expired keys, blocked accounts and deleted accounts cannot access the API.

Names and messages are untrusted input. Render them as text, never as HTML or executable code. Do not automate payment actions based on this feed.

Donation widget

Want to receive donations on your own website without sending visitors to DonoLink? Paste this iframe into your site's HTML and replace YOUR_USERNAME with your DonoLink name. No API key needed. Fees, payment methods, messages, alerts and payouts work exactly as on your donation page.

<iframe
  src="https://donolink.nl/embed/YOUR_USERNAME"
  title="DonoLink"
  width="100%"
  height="760"
  style="border:0;max-width:480px"
  allow="payment"
></iframe>

Options: append ?thema=licht to the URL for a light theme (dark by default) and ?bedrag=500 to prefill an amount in cents. Keep allow="payment": without it Apple Pay and Google Pay don't work inside the iframe. The widget is at most 480 pixels wide; a height of about 760 pixels shows the full form.

Card, Apple Pay and Google Pay complete inside the widget, after which the visitor sees a thank-you message. With iDEAL, Bancontact and Klarna the payment step opens in a new tab, because banks don't load inside another website; your site stays open. Bizum is not available in the widget.

The widget adds no analytics or cookie banner to your site. Payment details go straight to Stripe; your website never sees them. Only the /embed page may be embedded on other sites; your dashboard and regular donation page may not.

Code with your own name and preview in Settings