Skip to navigation
Notifications

API · Notify · Send a notification from an AI agent to a user

View as Markdown

Sends a single notification. It is routed through the notification registry, which determines delivery channels (in-app, websocket, email, Slack) based on the category.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
userIdstringRequired<=18 characters
ID of the user to notify
workspaceIdstringRequired<=18 characters
ID of the workspace
titlestringRequired<=250 characters

Short headline (sentence case). Becomes the email subject and the heading shown at the top of the email and in-app notification. Do NOT repeat the title inside message or body.

messagestringRequired<=4000 characters

One- or two-line summary for the in-app card, push and websocket. Keep it short and scannable. Used as the email/Slack body when body is omitted.

categoryenumRequired

Determines delivery channels: - agentTaskCompleted — in-app + websocket + email - agentNeedsInput — in-app + websocket + email - agentError — in-app + websocket + Slack (#agent-alerts) - agentProgress — websocket only - agentNudge — in-app + websocket + email

Allowed values:
threadIdstringOptional<=64 characters

Optional. ID of the agent conversation/thread this notification originated from. Used to build a deep link back to the conversation (e.g. the email CTA) when link is not supplied. Authoritative — injected from run config, never model-supplied.

bodystringOptional<=8000 characters

Optional long-form content in Markdown, written as a complete email: open with a greeting (e.g. "Hi Sarah,"), give the summary or report, and close with a brief sign-off. Rendered as the email body AND the Slack message. Use this (not message) when you have a detailed write-up. Do NOT restate the title. Falls back to message when omitted.

ctaLabelstringOptional<=40 characters

Optional label for the email/Slack action button. Defaults to "Continue the conversation" when a thread exists, else "View details".

_extraobjectOptional

Arbitrary metadata stored in the notification's JSON field. Frontend uses event_type to render each card differently.

Response

Notification(s) sent successfully

statusstringOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error