Messages API
Send a message with one HTTP request. Fields, responses and retry rules below.
Endpoint
POST https://appkeepr.com/api/messagesUse a workspace API token and an existing channel. Follow Quickstart to create both.
The full schema is available as OpenAPI.
Headers
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <workspace-api-token> |
Content-Type | Yes | application/json |
Idempotency-Key | No | Stable event ID for safe retries. |
Send a message
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" }| Status | Meaning |
|---|---|
400 | Invalid input. |
401 | Missing, invalid or revoked token. |
404 | Channel or project does not exist in this workspace. |
409 | Idempotency key was already used for different content. |
413 | Body exceeds 32 KiB. |
415 | Content type is not JSON. |
429 | Custom message request rate exceeded; honor Retry-After. |
503 | Could 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.
| Field | Meaning |
|---|---|
channel | Required existing channel name. |
body | Required text, 1–4,000 Unicode code points after trimming. |
title | Optional title, up to 180 code points after trimming. An empty title is omitted. |
project | Optional existing project name. Omitted or null means no project. |
icon | Optional single emoji sequence. |
sound | Optional notification sound: default, success, error, cash, attention, alarm or none. Omission uses default. |
fields | Up to 10 {label,value} pairs: label 80 and value 1,000 code points. Defaults to []. |
actions | Up to 3 {label,url} links: label 40 and URL 2,048 code points. HTTP(S) only, with no URL credentials. Defaults to []. |
occurredAt | Optional 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.