The drop.top API

OK

OK

What each event means — and, as important, what is deliberately absent:

• alert.sent fires when an alert becomes SENT: an immediate send, a published draft, or a scheduled alert being sent early by hand.
• alert.scheduled fires when the alert is scheduled, not at its send_at instant. Nothing runs at that minute by design — the alert becomes visible because the inbox query's send_at <= now() starts including it, which is the property that lets a server that was down deliver late rather than never. An event AT the instant is therefore impossible, and this is the honest substitute. If you need something to happen at send_at, schedule it yourself from this event's payload.
• alert.cancelled fires on withdrawal, with the usual caveat: phones that already received the alert keep it.
• subscriber.created / subscriber.deleted carry the pusher and a count, never anything device-shaped.
• There is no alert.delivered and no alert.failed, and there will not be: no per-device delivery row exists anywhere (a phone's inbox is a query), so an event claiming a delivery would be fiction.

Created. secret is shown once — store it.

Removed

Not found

OK

drop.top/<handle>. Lowercase letters, digits and single dashes; lowercased for you if you forget. No leading or trailing dash and no double dash (xn-- is the punycode prefix, and a handle that looks like an internationalised domain in a printed QR code is a phishing primitive). Route-shaped and official-looking words (admin, api, verified, …) are reserved and refused.

Required on create — it is the one line shown in search results.

https only, and this is the one place refusing cleartext costs a caller something real. It is refused anyway: this URL is opened from a notification a reader trusted, on a phone that may be on a café network — and the app's release build would refuse to load http regardless, so accepting it would store a link that can only fail later.

The geofence is all-or-nothing: lat, lon and radius_km together, or all null. A latitude with no radius describes no circle and would silently deliver nothing to a location-filtered subscriber — which presents as a channel that does not work rather than as a configuration mistake, so the half-filled form is a 422.

Kilometres, decimal. Small circles are legitimate — see the same field on an alert for what a handset's own accuracy does to one.

notify is added if you forget it — a channel that never asks for notify has asked for nothing at all. Unknown keys are dropped rather than rejected: an unknown key is a client from a newer build, and losing one permission is a better failure than losing the write.

Lowercased, deduplicated. Searched alongside the name.

false seals the channel: only a phone holding an invite code may subscribe or read what it has sent. Creating a channel private, or switching an open one to private, mints a first invite link and returns it as invite — a private channel with no way in would be a channel nobody, including its owner, can ever join. Existing subscribers are never removed by the switch.

The default is true, and omitting the field creates a channel anyone can find and join. That default is kept for compatibility with scripts written against it; the MCP create_pusher tool makes the field REQUIRED instead, because a model omitting a parameter is not the same act as an operator accepting a documented default.

https only.

Fallback-avatar gradient. An invalid colour keeps the current (or default) one.

Derived from the name when not supplied, so unbranded channels are not a column of identical grey circles.

Created

The handle is taken.

Validation failed

Over a ceiling. The message names it and when to retry. These limits fail open during a cache outage on purpose — the caller is authenticated and refusing real work to protect a counter would be backwards.

OK

Not found

Required on create — it is the one line shown in search results.

https only, and this is the one place refusing cleartext costs a caller something real. It is refused anyway: this URL is opened from a notification a reader trusted, on a phone that may be on a café network — and the app's release build would refuse to load http regardless, so accepting it would store a link that can only fail later.

The geofence is all-or-nothing: lat, lon and radius_km together, or all null. A latitude with no radius describes no circle and would silently deliver nothing to a location-filtered subscriber — which presents as a channel that does not work rather than as a configuration mistake, so the half-filled form is a 422.

Kilometres, decimal. Small circles are legitimate — see the same field on an alert for what a handset's own accuracy does to one.

notify is added if you forget it — a channel that never asks for notify has asked for nothing at all. Unknown keys are dropped rather than rejected: an unknown key is a client from a newer build, and losing one permission is a better failure than losing the write.

Lowercased, deduplicated. Searched alongside the name.

false seals the channel: only a phone holding an invite code may subscribe or read what it has sent. Creating a channel private, or switching an open one to private, mints a first invite link and returns it as invite — a private channel with no way in would be a channel nobody, including its owner, can ever join. Existing subscribers are never removed by the switch.

The default is true, and omitting the field creates a channel anyone can find and join. That default is kept for compatibility with scripts written against it; the MCP create_pusher tool makes the field REQUIRED instead, because a model omitting a parameter is not the same act as an operator accepting a documented default.

https only.

Fallback-avatar gradient. An invalid colour keeps the current (or default) one.

Derived from the name when not supplied, so unbranded channels are not a column of identical grey circles.

Pausing keeps the handle (nobody can impersonate a paused channel) and refuses sends until resumed.

OK

The channel is suspended — its status is staff's to change, not yours. error.type is forbidden; contact support.

Not found

Validation failed

Deleted, handle freed.

Not found

The channel still has subscribers. Pause it instead.

OK

Not found

Where this link went, in your words. Never shown to a subscriber.

How many phones may join with it. Null for unlimited; a one-shot link is 1.

When it stops working. Null for never. A time in the past is a 422 rather than a row: it would be a link that has never worked and cannot be told apart, in the list, from one that worked yesterday.

Created

Not found

Validation failed

Also unsubscribe the devices that joined with this link.

Revoked

Not found

An ISO 8601 instant — rows created strictly before it.

OK

Not found

Validation failed

The irreversible bit. Requires alerts:send. With a future send_at this schedules; without one it publishes immediately; false saves a draft.

A ceiling, not a command — and it defaults to the quiet one, which is the only reading under which a caller that never mentions loudness cannot accidentally be loud. An explicitly wrong value is still a 422; there is no guessing, only an absence with an obvious meaning.

https only. Satisfies layout: image on its own, as does image_asset_id; one of the two is required for that layout.

A picture UPLOADED to this service rather than linked. The alert then travels with image_url pointing at our own media route, so nothing on the phone distinguishes the two — and this field wins where both are set.

THE ID IS MINTED IN THE STUDIO, NOT HERE. Uploading is a browser problem — a file on somebody's desktop — and the three calls that do it are session-authenticated and deliberately outside this contract, for the same reason cover_url exists and a cover upload endpoint does not. A script already has a URL for its picture and should send image_url. This field is documented because the studio composes through this endpoint and you will see it on the wire.

Sending null detaches an uploaded picture from a draft.

The same arrangement for the alert's sound file: an upload we hold, surfaced to the phone as audio_url. Wins over audio_url where both are set, and null detaches it.

An uploaded .html file, kept as the author wrote it. IT IS NOT WHAT PHONES RENDER: the file's text is put through exactly the sanitiser (or, for layout: document, the sandbox) that html below goes through, and the result is what is stored and sent. The file itself is a record you can download back, served as text/plain and as an attachment — never as markup, from any origin.

Send it INSTEAD of html and the file's contents become the body. Send BOTH and html wins — the file is then only a record of where the body came from. That order exists because the studio uploads a file, shows its text in an editable box, and sends the box: if the file won, every edit made after uploading would vanish at the moment of sending. Null detaches.

Required when layout is html or document. For html it is sanitised (at most 60,000 characters) and the removals come back in blocked; for document the page is kept whole up to four times that, rendered in the phone's sandboxed iframe where scripts are inert. POST /v1/drop/preview runs the identical code without storing anything.

Puts the acknowledgement button on the card. Combined with expires_at, the window must stay open at least 5 minutes — the reader may be asleep, and an acknowledgement window shorter than the time it takes to pick up a phone produces a dashboard that says nobody responded to an evacuation instruction.

With send: true, a future instant schedules; the alert becomes visible at that moment with no scheduler involved, so a server that was down at the minute delivers late rather than never.

"Stop treating this as current", not "pretend it never happened" — phones move it out of the spotlight and stop ringing, but a reader can still scroll back to last night's storm warning. Must be after send_at.

A tone id, not a file — the phone synthesises it, so it costs no asset, no decode latency, and no network at the one moment the phone may have none. default and anything unrecognised both store null, meaning "whatever this priority already sounds like": a retired tone id loses the tone, never the alert. silent is a choice, not an absence. Heard only if the channel asked for sound AND the subscriber granted it — otherwise the alert arrives quietly and the create response's notes says so.

An absolute https URL to an mp3 — or any audio the handset can decode — STREAMED at the moment the alert arrives. A jingle, the siren a city already uses, a recorded sentence in a voice the reader knows.

IT WINS OVER sound, AND sound IS ITS FALLBACK. The phone gives the fetch a few seconds; if it is slow, refused, unplayable or the phone has no network, the tone id plays instead. So attaching a file can never be the reason an alert was silent — which is the only arrangement under which streaming audio belongs in an emergency path at all.

Not proxied, not cached and not transcoded: the URL travels to the phone exactly as written and the phone fetches it from wherever you put it, so it must be publicly reachable with no login. A phone plays at most 20 seconds. Heard only where the channel asked for sound AND the subscriber granted it — the create response's notes says so when it did not.

Same rules as sound: default and unknowns store null ("what this priority already does"); none stores, because "do not buzz" is a choice and not an absence.

What a phone reads aloud, where the channel asked for tts and the subscriber granted it. 400 characters because that is what the phone's speech call clamps to — storing more would store a sentence cut off at the moment it is spoken.

BCP-47, e.g. "nl-BE". Null falls back to the phone's own language.

An alert's own circle — all three of lat/lon/radius_km or none, exactly like the channel's. It may NARROW the channel's area and never widen it: the subscribe screen already told every subscriber where this channel operates, and an alert reaching past that would make the one disclosure they read a false one. A channel with no circle of its own may target anywhere.

Kilometres, decimal — 0.05 is a 50-metre circle around one platform or one gate, and that is a supported thing to want. Containment against the channel area allows 2% of the CHANNEL radius, at least 10 m: enough that a circle poking a few metres over a hand-drawn boundary is accepted, not enough to double the area. Note what the number cannot buy — a handset locates itself to within roughly 5-20 m outdoors and tens of metres indoors, so a circle smaller than that alerts some people just outside it and misses some just inside it.

An author label — "storm-14", "gate-change" — that makes a newer alert replace an older one in the notification shade instead of piling up. A slug on purpose: the value is hashed into a notification id on two sides of a language boundary, and restricting the alphabet is what stops a key that round-trips differently producing two entries where the author expected one.

Created — as a draft, scheduled, or already sent; read status.

Either insufficient_scope (send: true without alerts:send — the WWW-Authenticate header is present and names the scope) or forbidden (the pusher is suspended and cannot send).

Not found

The pusher is paused. A creator who paused a channel and then sent an alert has contradicted themselves, and the resolution they want is this message — not an alert that goes nowhere. Resume it, or save the alert as a draft.

Validation failed

Over a ceiling. The message names it and when to retry. These limits fail open during a cache outage on purpose — the caller is authenticated and refusing real work to protect a counter would be backwards.

OK

Not found

Requires alerts:send, both of them.

A ceiling, not a command — and it defaults to the quiet one, which is the only reading under which a caller that never mentions loudness cannot accidentally be loud. An explicitly wrong value is still a 422; there is no guessing, only an absence with an obvious meaning.

https only. Satisfies layout: image on its own, as does image_asset_id; one of the two is required for that layout.

A picture UPLOADED to this service rather than linked. The alert then travels with image_url pointing at our own media route, so nothing on the phone distinguishes the two — and this field wins where both are set.

THE ID IS MINTED IN THE STUDIO, NOT HERE. Uploading is a browser problem — a file on somebody's desktop — and the three calls that do it are session-authenticated and deliberately outside this contract, for the same reason cover_url exists and a cover upload endpoint does not. A script already has a URL for its picture and should send image_url. This field is documented because the studio composes through this endpoint and you will see it on the wire.

Sending null detaches an uploaded picture from a draft.

The same arrangement for the alert's sound file: an upload we hold, surfaced to the phone as audio_url. Wins over audio_url where both are set, and null detaches it.

An uploaded .html file, kept as the author wrote it. IT IS NOT WHAT PHONES RENDER: the file's text is put through exactly the sanitiser (or, for layout: document, the sandbox) that html below goes through, and the result is what is stored and sent. The file itself is a record you can download back, served as text/plain and as an attachment — never as markup, from any origin.

Send it INSTEAD of html and the file's contents become the body. Send BOTH and html wins — the file is then only a record of where the body came from. That order exists because the studio uploads a file, shows its text in an editable box, and sends the box: if the file won, every edit made after uploading would vanish at the moment of sending. Null detaches.

Required when layout is html or document. For html it is sanitised (at most 60,000 characters) and the removals come back in blocked; for document the page is kept whole up to four times that, rendered in the phone's sandboxed iframe where scripts are inert. POST /v1/drop/preview runs the identical code without storing anything.

Puts the acknowledgement button on the card. Combined with expires_at, the window must stay open at least 5 minutes — the reader may be asleep, and an acknowledgement window shorter than the time it takes to pick up a phone produces a dashboard that says nobody responded to an evacuation instruction.

With send: true, a future instant schedules; the alert becomes visible at that moment with no scheduler involved, so a server that was down at the minute delivers late rather than never.

"Stop treating this as current", not "pretend it never happened" — phones move it out of the spotlight and stop ringing, but a reader can still scroll back to last night's storm warning. Must be after send_at.

A tone id, not a file — the phone synthesises it, so it costs no asset, no decode latency, and no network at the one moment the phone may have none. default and anything unrecognised both store null, meaning "whatever this priority already sounds like": a retired tone id loses the tone, never the alert. silent is a choice, not an absence. Heard only if the channel asked for sound AND the subscriber granted it — otherwise the alert arrives quietly and the create response's notes says so.

An absolute https URL to an mp3 — or any audio the handset can decode — STREAMED at the moment the alert arrives. A jingle, the siren a city already uses, a recorded sentence in a voice the reader knows.

IT WINS OVER sound, AND sound IS ITS FALLBACK. The phone gives the fetch a few seconds; if it is slow, refused, unplayable or the phone has no network, the tone id plays instead. So attaching a file can never be the reason an alert was silent — which is the only arrangement under which streaming audio belongs in an emergency path at all.

Not proxied, not cached and not transcoded: the URL travels to the phone exactly as written and the phone fetches it from wherever you put it, so it must be publicly reachable with no login. A phone plays at most 20 seconds. Heard only where the channel asked for sound AND the subscriber granted it — the create response's notes says so when it did not.

Same rules as sound: default and unknowns store null ("what this priority already does"); none stores, because "do not buzz" is a choice and not an absence.

What a phone reads aloud, where the channel asked for tts and the subscriber granted it. 400 characters because that is what the phone's speech call clamps to — storing more would store a sentence cut off at the moment it is spoken.

BCP-47, e.g. "nl-BE". Null falls back to the phone's own language.

An alert's own circle — all three of lat/lon/radius_km or none, exactly like the channel's. It may NARROW the channel's area and never widen it: the subscribe screen already told every subscriber where this channel operates, and an alert reaching past that would make the one disclosure they read a false one. A channel with no circle of its own may target anywhere.

Kilometres, decimal — 0.05 is a 50-metre circle around one platform or one gate, and that is a supported thing to want. Containment against the channel area allows 2% of the CHANNEL radius, at least 10 m: enough that a circle poking a few metres over a hand-drawn boundary is accepted, not enough to double the area. Note what the number cannot buy — a handset locates itself to within roughly 5-20 m outdoors and tens of metres indoors, so a circle smaller than that alerts some people just outside it and misses some just inside it.

An author label — "storm-14", "gate-change" — that makes a newer alert replace an older one in the notification shade instead of piling up. A slug on purpose: the value is hashed into a notification id on two sides of a language boundary, and restricting the alphabet is what stops a key that round-trips differently producing two entries where the author expected one.

The alert after the edit or action.

The credential lacks a scope this request needs — error.type is insufficient_scope and the message names the scope and the place to fix it (mint a key carrying it, or disconnect and reconnect the assistant, approving it this time). Distinct from forbidden so a client can tell "get a better credential" apart from "this is not yours".

Not found

The state refuses the verb: sending a CANCELLED alert, sending while the pusher is not active, or editing a SENT or CANCELLED alert. The message names the way out (resume, duplicate, or cancel-and-correct).

Validation failed

Over a ceiling. The message names it and when to retry. These limits fail open during a cache outage on purpose — the caller is authenticated and refusing real work to protect a counter would be backwards.

Deleted

Not found

The alert was sent — it is the record of what was said and when.

At most 60,000 characters for html, four times that for document — the same caps the write path enforces.

The sanitised result — exactly what an alert body would store.

Validation failed

Over a ceiling. The message names it and when to retry. These limits fail open during a cache outage on purpose — the caller is authenticated and refusing real work to protect a counter would be backwards.

OK

Not found

OK

Not found

Validation failed

An ISO 8601 instant — subscriptions created strictly before it.

OK

Not found

Validation failed

OK

Validation failed