Jump toNotifications

Notifications

In-app notifications, preferences and the organization's rules.

get/v1/notification_preferences

List preferences

Any key of this organization

Response200

objectstring
list
dataNotificationPreference[]
5 fields
- channelstring
  One ofemailin_app
- digeststring
  One ofinstanthourlydaily
- enabledboolean
- typestring
- workspace_idstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notification_preferences" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "channel": "email",
      "digest": "instant",
      "enabled": true,
      "type": "type",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

put/v1/notification_preferences

Set preference

Any key of this organization

Request bodyPreferenceBody

channelstringRequired
One ofemailin_app
enabledbooleanRequired
typestringRequired
at most 100 characters
digeststring
One ofinstanthourlydailyDefault"instant"
workspace_idstring or null

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/notification_preferences" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "digest": "instant",
    "enabled": true,
    "type": "type",
    "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
  }'

get/v1/notification_rules

List rules

Needs notification.manage

Response200

objectstring
list
dataNotificationRule[]
15 fields
- objectstring
  notification_rule
- categorystring
- channelsstring[]
  One ofin_appemail
- default_digest_minutesinteger or null
- digest_minutesinteger or null
- effectiveNotificationRuleEffective
  3 fields
  digest_minutesinteger or null
  emailboolean
  in_appboolean
- email_enabledboolean or null
- in_app_enabledboolean or null
- mute_emailboolean
- mute_in_appboolean
- provider_idstring or null
- severitystring
  One ofinfoactionwarningcritical
- titlestring
- typestring
- updated_atstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notification_rules" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "notification_rule",
      "category": "category",
      "channels": [
        "in_app"
      ],
      "default_digest_minutes": 2,
      "digest_minutes": 2,
      "effective": {
        "digest_minutes": 2,
        "email": true,
        "in_app": true
      },
      "email_enabled": true,
      "in_app_enabled": true,
      "mute_email": true,
      "mute_in_app": true,
      "provider_id": "provider id",
      "severity": "info",
      "title": "Support triage",
      "type": "type",
      "updated_at": "2026-11-10T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/notification_types

Notification types

Any key of this organization

Response200

objectstring
list
dataNotificationTypeInfo[]
7 fields
- channelsstring[]
  One ofin_appemail
- digest_minutesinteger or null
- mute_emailboolean
- mute_in_appboolean
- severitystring
  One ofinfoactionwarningcritical
- titlestring
- typestring
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notification_types" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "channels": [
        "in_app"
      ],
      "digest_minutes": 2,
      "mute_email": true,
      "mute_in_app": true,
      "severity": "info",
      "title": "Support triage",
      "type": "type"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/notifications

List notifications

Any key of this organization

Newest first (order=created_at for oldest first). q searches the headline (or finds a pasted ntf_…). Filters, each repeatable: read (read, unread; unread=true is the same as read=unread), type, severity and workspace_id (ws_…; workspace is its older name), plus the created time range; facets count each (workspace_id by public ID; organization-wide notifications have none).

Query parameters

unreadboolean
Defaultfalse
readstring[]
typestring[]
severitystring[]
workspace_idstring[]
Only rows in this workspace (ws_…).
limitinteger
Rows per page, 1 to 200.
Default50at least 1at most 200
cursorstring
qstring
Search: rows whose name (or the list's other searchable text) contains this, any case.
at most 200 characters
orderstring
Sort field; a leading - sorts down. Each list names the fields it sorts by.
at most 64 charactersmatches ^-?[a-z_]+$
includestring[]
total_count (counted up to 10,000) and facets (a count per filter value).
One oftotal_countfacets
created_afterstring
Only rows created at or after this time (RFC 3339).
date-time
created_beforestring
Only rows created at or before this time (RFC 3339).
date-time
updated_afterstring
Only rows last changed at or after this time (RFC 3339).
date-time
updated_beforestring
Only rows last changed at or before this time (RFC 3339).
date-time

Response200

objectstring
list
dataNotification[]
12 fields
- idstring
- objectstring
  notification
- archived_atstring or null
- created_atstring or null
- paramsobject
  Any JSON object.
- readboolean
- read_atstring or null
- resourceNotificationResource or null
  3 fields
  idstring
  typestring
  workspace_idstring or null
- severitystring
  One ofinfoactionwarningcritical
- titlestring
- typestring
- workspace_idstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notifications?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "ntf_01jcgbfa525gz2943pdr7ahcby",
      "object": "notification",
      "archived_at": null,
      "created_at": "2026-11-10T09:30:00.000Z",
      "params": {},
      "read": true,
      "read_at": "2026-11-10T09:30:00.000Z",
      "resource": {
        "id": "id",
        "type": "type",
        "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
      },
      "severity": "info",
      "title": "Support triage",
      "type": "type",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/notifications/read_all

Read all

Any key of this organization

Response200

objectstring
notifications_marked
updatedinteger

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/notifications/read_all" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "notifications_marked",
  "updated": 2
}

get/v1/notifications/unread_count

Unread count

Any key of this organization

Response200

objectstring
notification_count
unreadinteger

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notifications/unread_count" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "notification_count",
  "unread": 2
}

put/v1/notification_rules/{notification_type}

Set rule

Needs notification.manage

Null for a field keeps the catalogue default; all null removes the rule.

Path parameters

notification_typestringRequired

Request bodyRuleBody

digest_minutesinteger or null
at least 0at most 10080
email_enabledboolean or null
in_app_enabledboolean or null
provider_idstring or null

Response200

objectstring
notification_rule
categorystring
channelsstring[]
One ofin_appemail
default_digest_minutesinteger or null
digest_minutesinteger or null
effectiveNotificationRuleEffective
3 fields
- digest_minutesinteger or null
- emailboolean
- in_appboolean
email_enabledboolean or null
in_app_enabledboolean or null
mute_emailboolean
mute_in_appboolean
provider_idstring or null
severitystring
One ofinfoactionwarningcritical
titlestring
typestring
updated_atstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/notification_rules/run.failed" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "digest_minutes": 2,
    "email_enabled": true,
    "in_app_enabled": true,
    "provider_id": "provider id"
  }'

Response · 200

JSON

{
  "object": "notification_rule",
  "category": "category",
  "channels": [
    "in_app"
  ],
  "default_digest_minutes": 2,
  "digest_minutes": 2,
  "effective": {
    "digest_minutes": 2,
    "email": true,
    "in_app": true
  },
  "email_enabled": true,
  "in_app_enabled": true,
  "mute_email": true,
  "mute_in_app": true,
  "provider_id": "provider id",
  "severity": "info",
  "title": "Support triage",
  "type": "type",
  "updated_at": "2026-11-10T09:30:00.000Z"
}

get/v1/notifications/{notification_id}

Get notification

Any key of this organization

The page an email links to (/notifications/{ntf}?org=…) reads this; declared after the fixed paths above so unread_count is never taken for an ID.

Path parameters

notification_idstringRequired

Response200

idstring
objectstring
notification
archived_atstring or null
created_atstring or null
paramsobject
Any JSON object.
readboolean
read_atstring or null
resourceNotificationResource or null
3 fields
- idstring
- typestring
- workspace_idstring or null
severitystring
One ofinfoactionwarningcritical
titlestring
typestring
workspace_idstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/notifications/ntf_01jcgbfa525gz2943pdr7ahcby" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "ntf_01jcgbfa525gz2943pdr7ahcby",
  "object": "notification",
  "archived_at": null,
  "created_at": "2026-11-10T09:30:00.000Z",
  "params": {},
  "read": true,
  "read_at": "2026-11-10T09:30:00.000Z",
  "resource": {
    "id": "id",
    "type": "type",
    "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
  },
  "severity": "info",
  "title": "Support triage",
  "type": "type",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

post/v1/notifications/{notification_id}/archive

Archive one

Any key of this organization

Path parameters

notification_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/notifications/ntf_01jcgbfa525gz2943pdr7ahcby/archive" \
  -H "Authorization: Bearer $MDA_API_KEY"

post/v1/notifications/{notification_id}/read

Read one

Any key of this organization

Path parameters

notification_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/notifications/ntf_01jcgbfa525gz2943pdr7ahcby/read" \
  -H "Authorization: Bearer $MDA_API_KEY"

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide