Messages
Send a message with POST /api/messages.
Endpoint
POST https://appkeepr.com/api/messagesUse a workspace API token and an existing channel. Follow Quickstart to create both.
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://example.com/users/1044"}]
}'Responses
201 Created — a new message was created.
{ "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 | Workspace capacity 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; unknown properties are rejected and the body limit is 32 KiB.
| 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. |
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. |
Channel and project must already exist in the token's workspace. Use their exact names: 1–120 lowercase ASCII letters, numbers and single hyphens between words.
Idempotency
Set the optional Idempotency-Key header to your stable event ID. It accepts 1–220 visible ASCII characters without spaces.
Retry with the same key, channel, project and content, including occurredAt if you supplied it. Reusing a key with different content returns 409.
Keys are scoped to a channel and remain valid after token changes or monthly resets.
Retry safely
A timed-out request may have succeeded. Retry with the same key and content.