Messages

POST /v1/messages accepts a typed notification and queues it for delivery to the user's devices. New senders should use the first-class substance fields below so iOS/admin can render useful prompt, command, file, and subagent context without parsing boilerplate from message.

Production URL:

POST https://notifier.aicrew.in/api/v1/messages

Required auth:

X-API-Key: an_key_REPLACE_WITH_YOUR_KEY

Minimal request

{
  "type": "alert",
  "title": "Build finished",
  "message": "main passed in 4m 12s"
}

Full request shape

Substance-first rendering contract

The API still accepts title and message, but the current iOS/admin renderers prefer structured substance fields:

• title should be a short verb phrase, for example Run tool: Bash, Prompt submitted, or Session ended.
• message should be the useful content only: the prompt excerpt, command, file summary, output summary, or error detail.
• Project name, event name, status, and session identity should be sent as fields/chips, not repeated as project: X · event: Y · status: Z prose.
• metadata remains useful for safe hashes, lengths, durations, source labels, and back-compat hook context.
• file_paths describes local context only. If a sender wants the app/user to open files, upload each file to /v1/media and send the returned structured objects in attachments. Images still backfill legacy image_url; non-image files can also populate url/url_title for older clients.

Idempotency and retries

Unattended agents and CLIs should generate a UUID client_event_id for each logical event and keep it stable across automatic retries. The backend enforces uniqueness per project: if the same project receives the same client_event_id again, it returns the original notification ID instead of inserting a duplicate.

Do not hard-code example UUIDs in long-lived scripts. Generate a new value per logical notification, then reuse that value only while retrying that notification after a timeout, 429, or transient 5xx response.

Rich example

AGENT_NOTIFIER_API_BASE="${AGENT_NOTIFIER_API_BASE:-https://notifier.aicrew.in/api/v1}"
CLIENT_EVENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"

curl -sS -X POST "$AGENT_NOTIFIER_API_BASE/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AGENT_NOTIFIER_API_KEY" \
  --data @- <<JSON
{
    "project": "Release Bot",
    "client_event_id": "$CLIENT_EVENT_ID",
    "type": "progress",
    "title": "Deploying 1.2.3",
    "message": "Smoke tests are running",
    "event": "PostToolUse",
    "tool_name": "Bash",
    "command": "npm run test:e2e",
    "file_paths": ["admin/e2e/launch.spec.ts"],
    "status": "running",
    "priority": 0,
    "color": "blue",
    "progress": 0.72,
    "url": "https://github.com/yashness/agent-notifier/actions",
    "url_title": "View workflow",
    "buttons": ["Approve", "Retry", "Rollback"],
    "sound": "cosmic",
    "ttl": 300
}
JSON

Server-side audio example

Use as_audio when an agent should send media plus generated speech without blocking the caller:

AGENT_NOTIFIER_API_BASE="${AGENT_NOTIFIER_API_BASE:-https://notifier.aicrew.in/api/v1}"
CLIENT_EVENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"

curl -sS -X POST "$AGENT_NOTIFIER_API_BASE/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AGENT_NOTIFIER_API_KEY" \
  --data @- <<JSON
{
    "project": "Release Bot",
    "client_event_id": "$CLIENT_EVENT_ID",
    "type": "alert",
    "title": "Deployment complete",
    "message": "The deployment finished successfully and smoke tests passed.",
    "priority": 0,
    "as_audio": true,
    "attachments": [
      {
        "kind": "file",
        "url": "https://notifier.aicrew.in/media/release-notes.md",
        "mime_type": "text/markdown",
        "size_bytes": 2048,
        "file_name": "release-notes.md"
      }
    ],
    "tts_text": "Release notes markdown content can be supplied here when the audio should read the attached file.",
    "voice_engine": "kokoro",
    "voice": "af_bella",
    "speed": 1.0,
    "rewrite_for_tts": false
}
JSON

The response includes the notification id and audio_status: "queued". The backend stores metadata.tts_status as queued, then running, then ready or failed. When audio is ready, the generated audio is prepended to attachments, exposed as the legacy primary attachment, and delivered in the rich push.

To check status without a user JWT, call GET /api/v1/messages/{id}/status with the same X-API-Key. The response includes audio_status, attachments_count, the primary attachment, all attachments, and safe metadata.

Hook metadata

Hooks should put core renderer context in the top-level substance fields and auxiliary/back-compat context in metadata. The API keeps /v1/messages compatible by accepting a flat object of string values, sanitizing secret-like keys/values, truncating long values, and returning the same safe metadata in feed/action-response payloads.

Stable hook.v1 keys include:

Excerpt keys and top-level prompt/command are intended for UI rendering and must be locally redacted before send. Local proof logs omit excerpt fields and keep only hashes/lengths/status so API keys, bearer tokens, private keys, APNs material, SAS signatures, and prompt/command bodies do not leak into diagnostics.

Response

Successful sends return HTTP 202:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "delivered_at": "2026-04-26T00:00:00Z",
  "project_name": "Release Bot",
  "user_hash": "a1b2c3d4e5f6"
}

The API response means the message was accepted for delivery. project_name and user_hash are diagnostics for account-scoped API keys and account mismatch troubleshooting; APNs delivery and user interaction happen asynchronously.