publish api json form-urlencoded text/plain

Publish API

Send one notification request, derive one public channel code, and verify delivery without leaving the docs page.

Auth

/<publishKey> or generated on /

Route

POST /<publishKey>, POST /, GET / (CLI)

Formats

JSON, form-urlencoded, or plain text

Verify

Open derived channel page or reuse generated publish URL

01 · Overview

Smallest useful mental model

Keep the workflow tight: key in, request out, channel page for verification.

Public identifier

A channelCode is derived from the publishKey.

Request formats

With no content-type header, the server tries JSON first, then form-urlencoded, then plain text.

Publish routes

POST /<publishKey> sends directly with a known key. POST / generates a random publish key, sends once, and returns it in the response. GET / returns a bootstrap payload for CLI user agents such as curl.

App-aware keys

severity, show, ring, and level only matter for behavior overrides.

02 · Quick start

First successful publish

curl -X POST https://alrim.io/<publishKey> \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Server deploy",
    "body": "v1.2.3 shipped",
    "data": {
      "severity": "warning",
      "ring": "force",
      "level": "2"
    }
  }'

Read in order

1. Paste a publishKey between 32 and 256 characters using only lowercase letters and digits.
2. Start with the path route so the key and payload stay visible in one request.
3. Open the derived channel page after success to confirm delivery.

03 · Authentication

Path auth first, headers optional

Path-based: POST /<publishKey> is the most direct route when you already know the publish key.

Root route: POST / generates a random publish key and returns it alongside the send result. GET / returns a CLI bootstrap envelope only for curl-like user agents.

Content type: you do not have to define a content-type header for these examples. With no header, the server tries JSON first, then form-urlencoded, then plain text.

Header-based: still works via X-Alrim-Key or Authorization: Bearer if your integration prefers hidden keys.

Validation: trimmed keys must be at least 32, at most 256, and use only lowercase letters a-z plus digits 0-9.

Auth header

X-Alrim-Key: <publishKey>
Authorization: Bearer <publishKey>

04 · Publish routes

Path and root route examples

POST /<publishKey>

Accepts JSON, form-urlencoded, or plain text. Plain text defaults the title to alrim and uses the raw request body as body.

curl -X POST https://alrim.io/<publishKey> \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Smoke test",
    "body": "publish key in path"
  }'

POST /<publishKey>

JSON body with an explicit application/json content-type header.

Selected format

curl -X POST https://alrim.io/<publishKey> \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Smoke test",
    "body": "publish key in path"
  }'

POST /

Generates a random publish key, sends the notification once, and returns both the send result and the generated publish URL.

curl -X POST https://alrim.io/ \
  -H 'Content-Type: application/json' \
  --data-binary '{"title":"Server deploy","body":"v1.2.3 shipped"}'

GET / (CLI only)

When the request user agent looks like a CLI tool such as curl, the root GET route returns a bootstrap JSON payload with a generated publish key and ready-to-copy curl commands.

Root GET

curl https://alrim.io/

05 · Request body

JSON payload shape

Keep the top level small: title, body, and optional data. The server injects a few internal fields before FCM delivery.

Payload

{
  "title": "Server deploy",
  "body": "v1.2.3 shipped",
  "data": {
    "severity": "warning",
    "show": "1",
    "ring": "force",
    "level": "2"
  }
}

Field notes

Auto injected: channel_code, title, body, alrim_created_at_ms, notification_id

Headers: not required for the path-based examples on this page. With no header, the server tries JSON first, then form-urlencoded, then plain text.

App aware: severity, show, ring, level

06 · Responses

Response envelopes

POST /<publishKey> returns the direct notify result. POST / adds generated publish key metadata on top of the send result. GET / for CLI user agents returns only the generated publish key bootstrap payload.

POST /<publishKey> success

Success

{
  "ok": true,
  "channel_code": "3ba3f5f43b92602683c19aee62a20342",
  "channel_url": "https://alrim.me/3ba3f5f43b92602683c19aee62a20342",
  "notification_id": "d6d5f95b3bbd4fb4b8d98f7bc8e89c17",
  "created_at_ms": 1712345678901
}

POST / failure

Error

{
  "ok": false,
  "error": "publishKey must use only lowercase letters (a-z) and digits (0-9). See https://alrim.io/doc for publishKey rules and examples."
}

POST / success with generated publish key

Root POST response

{
  "ok": true,
  "publish_key": "5765aff90d6e4d2e169b3b496c418cc9",
  "publish_url": "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9",
  "channel_code": "3ba3f5f43b92602683c19aee62a20342",
  "channel_url": "https://alrim.me/3ba3f5f43b92602683c19aee62a20342",
  "notification_id": "d6d5f95b3bbd4fb4b8d98f7bc8e89c17",
  "created_at_ms": 1712345678901,
  "curl": "curl -X POST "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9" ..."
}

GET / CLI bootstrap response

Root GET response

{
  "ok": true,
  "publish_key": "5765aff90d6e4d2e169b3b496c418cc9",
  "publish_url": "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9",
  "curl": "curl -X POST "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9" ...",
  "curl_json": "curl -X POST "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9" ...",
  "curl_form": "curl -X POST "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9" ...",
  "curl_text": "curl -X POST "https://alrim.io/5765aff90d6e4d2e169b3b496c418cc9" ..."
}

07 · Examples

Copy-ready requests

Path publishKey + selected request format

curl -X POST https://alrim.io/<publishKey> \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Server deploy",
    "body": "v1.2.3 shipped",
    "data": {
      "severity": "warning",
      "ring": "force",
      "level": "2"
    }
  }'

Format behavior

Selected format

curl -X POST https://alrim.io/<publishKey> \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Smoke test",
    "body": "publish key in path"
  }'