Get started

Messages API

Send a message with one HTTP request. Fields, responses and retry rules below.

Endpoint

POST https://appkeepr.com/api/messages

Use a workspace API token and an existing channel. Follow Quickstart to create both.

The full schema is available as OpenAPI.

Headers

HeaderRequiredValue
AuthorizationYesBearer <workspace-api-token>
Content-TypeYesapplication/json
Idempotency-KeyNoStable event ID for safe retries.

Send a message

Request
curl https://appkeepr.com/api/messages \
  -H "Authorization: Bearer $APPKEEPR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-1044" \
  -d '{
    "channel": "signups",
    "body": "Ada created an account.",
    "title": "New signup",
    "icon": "👋",
    "fields": [{"label": "Customer", "value": "Ada"}],
    "actions": [{"label": "Open profile", "url": "https://appkeepr.com/users/1044"}]
  }'

Responses

201 Created — your message is in the channel.

{ "messageId": "0f6211b8-9d26-4af1-83b2-a8cbd64a0378", "outcome": "created" }
StatusMeaning
400Invalid input.
401Missing, invalid or revoked token.
404Channel or project does not exist in this workspace.
409Idempotency key was already used for different content.
413Body exceeds 32 KiB.
415Content type is not JSON.
429Custom message request rate exceeded; honor Retry-After.
503Could not accept the message. Retry with the same key and content.

Request body

Only channel and body are required. Send JSON, up to 32 KiB. Unknown properties are rejected.

FieldMeaning
channelRequired existing channel name.
bodyRequired text, 1–4,000 Unicode code points after trimming.
titleOptional title, up to 180 code points after trimming. An empty title is omitted.
projectOptional existing project name. Omitted or null means no project.
iconOptional single emoji sequence.
soundOptional notification sound: default, success, error, cash, attention, alarm or none. Omission uses default.
fieldsUp to 10 {label,value} pairs: label 80 and value 1,000 code points. Defaults to [].
actionsUp to 3 {label,url} links: label 40 and URL 2,048 code points. HTTP(S) only, with no URL credentials. Defaults to [].
occurredAtOptional RFC3339 timestamp with UTC or an explicit offset. Defaults to the time the message is first accepted.

Use exact channel and project names from the token's workspace: 1–120 lowercase ASCII letters, numbers and single hyphens between words.

See Notification sounds for presets and device support. Sound values are case-sensitive; null, empty or unknown values return 400.

Rate limits

You get 100 valid requests per 10-second window, shared across your workspace's API tokens. Duplicates count too. Each server process applies its own window; integration webhooks are separate.

On 429 message_rate_limited, wait the number of seconds in Retry-After before trying again.

Idempotency

Use a stable event ID as Idempotency-Key: 1–220 visible ASCII characters, without spaces.

Keep the key, channel, project and content identical on retries, including occurredAt if you supplied it. Different content with the same key returns 409.

That includes sound: changing cash to error returns 409. Omitting sound and sending "sound": "default" are equivalent.

Keys are scoped to a channel and remain valid after token changes.

Retry safely

A timed-out request may have succeeded. Retry with the same key and content.

On this page