Introduction

The NotifyMe Management API lets you configure your notification setup from code instead of doing it by hand in the dashboard. Anything you'd normally set up there, like adding a YouTube channel, editing a notification message, or swapping an embed, you can do with an HTTP request.

WARNING

This API is in beta. Response fields and error formats may still change, and breaking changes will be announced in the NotifyMe Discord before they ship. There's no uptime commitment yet, so build things you can adjust quickly.

If you hit a bug, or something these docs don't cover, please report it in the Discord.

INFO

The Management API is a premium feature, currently available on the Advanced plan. See https://notifyme.bot/premium for which plans include API access.

Scope and intended use

WARNING

This is a management API, not a platform API. It exists so you can automate the management of your own servers. It is not a foundation to build a product on.

The API is intended for:

Configuring NotifyMe in servers you own or administrate.

Automating repetitive setup, like adding many accounts at once, applying the same embed across channels, or keeping a roster of creators in sync.

Internal tooling for your own community.

It is not intended for:

Building a product, service, or business that resells, wraps, or redistributes NotifyMe's functionality to other people.

Operating NotifyMe as the backend of another application or bot.

Offering NotifyMe configuration to third parties as a managed or whitelabel service.

Your API key is yours. Don't distribute it, don't embed it in a client-side application, and don't build a service that calls this API on behalf of other users. Keys found in use this way may be revoked.

INFO

If you're unsure which side of that line your project falls on, ask before you build. The Terms of Service is the binding version of the above.

What you can manage

Resource	What it is
Accounts	One social media profile NotifyMe watches, plus the Discord channel it posts to. Also where you trigger test and forced notifications.
Embeds	Reusable embed designs that notifications are rendered with.
Bot styles	Reusable name-and-avatar presets that notifications are posted under.

Supported platforms: youtube, tiktok, twitter, twitch, kick.

Base URL

https://public-api.notifyme.bot/v1/management

HTTPS only. All paths in the reference are relative to this.

How it fits together

A server has accounts. An account is one social media profile that NotifyMe watches, plus the Discord channel where its notifications get posted and an optional role to ping. Which events trigger a post is controlled by content types, what the message says is controlled by messages, and how it looks is controlled by an embed and a bot style.

Embeds and bot styles are independent objects. You create one, get its internal_id, and reference it from as many accounts as you like.

Content types vary by platform: video, live, and short for video platforms, tweet, retweet, and quoted for Twitter. The message object is keyed the same way, so message.live is the text sent when a stream goes live.

Message tags like {account}, {title}, and {link} are substituted at send time. Support varies by platform and by content type, so {game} only means something on platforms that report a game, and livestream-only tags produce nothing in a video notification. See Using Message Tags for the full list.

Before you begin

You'll need:

An active Advanced plan, or any plan that includes API access. Check https://notifyme.bot/premium.

A Discord server where you have Manage Server permission.

NotifyMe added to that server, with permission to send messages and embed links in your target channels.

An API key from your dashboard. Keys begin with nme_.

Your server ID. Enable Developer Mode in Discord, then right-click the server icon and choose Copy Server ID.

An API key is scoped to a single server. To manage more than one, generate a key for each.

Your first request

List the YouTube accounts configured in a server:

{
  "status": true,
  "data": [
    {
      "internal_id": "acc_8Kq1xZbA2f",
      "id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
      "url": "https://youtube.com/@GoogleDevelopers",
      "name": "Google for Developers",
      "status": true,
      "discord_channel_id": "1044159651178094595",
      "ping_role_id": "1044159651178094596",
      "customization": {
        "embed_internal_id": null,
        "bot_style_internal_id": null
      },
      "content_types": ["video", "live"],
      "message": {
        "video": "{ping_role} {account} just uploaded: {title}\n{link}",
        "live": "{account} is live now!\n{link}",
        "tweet": null
      },
      "created_at": "2026-07-14T09:31:02Z",
      "updated_at": "2026-07-29T18:04:55Z"
    }
  ]
}

Both server_id and platform are required. An empty data array means your key works and there's simply nothing configured for that platform yet.

Ready to add one? See Add account.

Conventions

CAUTION

Every ID is a string, always. Discord IDs are 64-bit snowflakes that exceed the safe integer range in JavaScript. Parse 1044159651178094592 as a number and the last digits silently change. Keep server_id, discord_channel_id, and ping_role_id as strings from end to end, and make sure your JSON parser isn't coercing them.


Auth	Send your key in the `X-API-Key` header. Required on every endpoint.
Format	JSON, UTF-8. Send `Content-Type: application/json` on requests with a body.
Field names	`snake_case`.
Timestamps	`created_at` and `updated_at` are ISO 8601 strings with both date and time, for example `2026-07-14T09:31:02Z`.
Envelope	Every response is `{ "status": <boolean>, "data": ... }`. Check `status` before reading `data`.
Two kinds of ID	`internal_id` is NotifyMe's identifier for an object, and it's what you use to edit or delete. `id` is the account's identifier on its own platform, such as a YouTube channel ID. They are not interchangeable.
`status` on an account	A boolean. `true` if the account is actively being watched, `false` if paused. Not to be confused with the response envelope's `status`.
Nulls	`ping_role_id`, the `customization` fields, and unused `message` keys are `null` when unset.
Query vs body	Reads take `server_id` and `platform` as query parameters. Writes take their payload as a JSON body.
Errors	Failures return `{ "status": false, "error": "<message>" }`, where `error` is a human readable string. Use the HTTP status code to decide what to do, not the message text.

Rate limits

Limits are set per endpoint and method rather than globally. Each endpoint page in the API Reference is the authoritative source, but here's the whole picture at a glance:

Endpoint	GET	POST	PATCH	DELETE
`/accounts`	5/sec	10/min	5/sec	5/sec
`/accounts/test`	—	10/min	—	—
`/accounts/force`	—	10/min	—	—
`/embeds`	5/sec	5/sec	5/sec	5/sec
`/bot-styles`	5/sec	5/sec	5/sec	5/sec

Adding accounts is the slowest path. POST /accounts allows 10 per minute, so filling a platform all the way to its 500 account cap takes just under an hour. Build a bulk import as a queue you can pause and resume rather than a loop you run once and hope finishes.

Test and force notifications are capped at 10 per minute because each one posts a real message into Discord. Don't use them to poll or verify state.

Account limit

The API will only add accounts to a platform that is under 500 accounts. This is an API-only safeguard against abuse. The dashboard has no such limit, so anyone who wants more can keep adding through the UI.

Two details worth being precise about:

The cap is per platform, not per server. A server that has filled its 500 YouTube slots can still add TikTok and Twitch profiles through the API.

The count includes every account on the server, however it was added. So a server that already holds 500 or more YouTube profiles set up through the dashboard will be refused on POST /accounts for YouTube, even though the dashboard would still accept more.

Once a platform is full, POST /accounts fails with 403 Forbidden:

{
  "status": false,
  "error": "The API on your server can only add accounts to platforms with fewer than 500 accounts. This server currently has 602 TikTok accounts. You can still add accounts from the dashboard, or contact support at https://discord.gg/notifyme to raise the API limit."
}

Retrying will never succeed. The limit is a default rather than a hard ceiling, so if you legitimately need more, ask in the support server.

When you hit a limit

Exceeding a rate limit returns 429 Too Many Requests with the standard error shape:

{
  "status": false,
  "error": "Too many requests. Retry in 12 seconds."
}

Along with these headers:

Header	Meaning
`Retry-After`	Whole seconds to wait before retrying.
`X-RateLimit-Limit`	The limit that applies to this endpoint and method.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Unix timestamp in seconds for when the window resets.

Wait for Retry-After, then retry. Don't retry immediately, and don't invent your own fixed interval, because the window length differs per endpoint. The error message repeats the same figure in plain English for anyone reading it by hand, but read the header rather than parsing the sentence, since wording can change and headers won't.

Branch on the status code, not the message. A 429 is temporary, so wait and retry. A 403 from the account limit is permanent, so retrying will never succeed and your client should surface it to the user instead of looping.

Delivery timing

Notification delivery isn't instant, and how fast it happens depends on the platform. Some platforms notify us directly, others we check on a schedule. Delivery is also bounded by Discord's own rate limits, so a server with many accounts firing at once will finish posting slightly after the first message lands.

Scope and intended use#

What you can manage#

Base URL#

How it fits together#

Before you begin#

Your first request#

Conventions#

Rate limits#

Account limit#

When you hit a limit#

Delivery timing#