Skip to content
Speak AIDocs

Read Speak AI in-app notifications with the API

List the in-app notifications in your Speak AI account, filter them by category such as label or comment activity, and mark your own as read.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

The Speak AI API exposes 2 notifications endpoints under the base URL https://api.speakai.co/v1. Every request needs the x-speakai-key and x-access-token headers described in Authentication.

The in-app notifications the Speak app lists under Notifications: uploads and analysis, payments, team changes, and label and comment activity. Read them a page at a time with filters, and mark your own as read.

What can you do with the notifications endpoints?

Speak AI groups these 2 endpoints under the notifications resource. Each entry below links to the full reference for that endpoint further down this page.

Notifications

Notifications

List notifications

GET/notification

Returns your company’s in-app notifications, newest first, a page at a time. The Speak app shows the same list under Notifications.

Who sees what

An owner sees every notification in the company. A member of one or more user groups sees their own notifications, the ones written for the people in those groups, and the ones assigned to those groups. Anyone else sees every notification in the company. filterUserId narrows the list to one person.

totalUnReadCount always counts only your own unread notifications, whatever filters you send.

Categories and actions

type is the category of a notification and action is what happened. Send either as a filter. An unknown type is ignored and returns every category, while an unknown action matches nothing.

Labels and comments

  • Label library: creating, editing, archiving, restoring or merging a label, or adding Speak label sets, writes type label with mediaType label for the person who made the change. mediaId holds the labelId.
  • Labels on a transcript: applying, changing or removing labels writes type label with actions created, updated or deleted. mediaId and mediaType name the file.
  • Comments: adding, editing, resolving, reopening or deleting a comment writes type comment for the person who did it, with actions created, updated, resolved, reopened or deleted.
  • Thread starters: the person who started a thread also gets a comment notification when someone else replies (replied), resolves it (resolved) or reopens it (reopened). They are not told about their own replies, and people who are no longer active members are not told.
  • Dashboard share links: turning labels or comments on or off on a dashboard’s share link, or changing its modes or reviewer names, writes type dashboard with mediaType dashboard, and mediaId holds the dashboardId.

Changes made through a dashboard share link are written for the link’s owner and end with “by <name> from a shared dashboard”.

Parameters

Parameter In Type Required Description
page query integer No Page to return, counting from 0. Leave it out for the first page.
pageSize query integer No Notifications per page. Leave it out for 50.
type query string No Only this category. One of the type values listed in the response schema, such as label, comment or dashboard. Any other value is ignored.
action query string No Only this action, such as replied, resolved or reopened. Matched exactly.
description query string No Text to look for in the description, ignoring case.
filterUserId query string No Only notifications written for this user id.
startDate query string (date-time) No Start of a date range on createdAt. Applied only together with endDate.
endDate query string (date-time) No End of a date range on createdAt. Applied only together with startDate.
sortBy query string No Field to sort by. Leave it out to sort by createdAt, newest first. Any other value is ignored.
sortDir query string No asc for ascending. Anything else sorts descending.
Example request
curl -X GET 'https://api.speakai.co/v1/notification?page=0&pageSize=50&type=comment&action=replied&description=Customer%20call&filterUserId=65f0c1a2b3c4d5e6f7a8b9c0&startDate=2026-10-01T00%3A00%3A00.000Z&endDate=2026-10-07T23%3A59%3A59.000Z&sortBy=createdAt&sortDir=desc' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 Success

Response body, application/json.

Field Type Description
status string success on every 2xx response. One of: success .
data object
data.totalCount integer How many notifications match the filters, across all pages.
data.totalUnReadCount integer How many of your own notifications are unread.
data.notificationList object[] This page of notifications.
data.notificationList – 12 more fields
Field Type Description
_id string Id of the notification.
mediaId string Id of what the notification is about: a media file, or a labelId when mediaType is label, or a dashboardId when mediaType is dashboard. Left out when it is about nothing in particular.
mediaType string What kind of thing mediaId names: audio, video or text for a file, label for a label or group, dashboard for a dashboard. Left out when there is no mediaId.
description string What happened, in words you can show to a person.
type string Category. One of: clip, audio, account, automation, embed, integration, magic prompt, media, payment, presentation, recorder, survey, subscription, team, text, transcription, translate, video, zapier, meeting assistant, google calendar, outlook calendar, auto reload, folder, fields, assistant template, knowledge base, label, comment, dashboard .
action string What happened. One of: analyzed, created, credit, debit, deleted, export, paid, updated, uploaded, error, failed, cloned, replied, archived, restored, merged, resolved, reopened .
amount number Amount on payment and credit notifications.
transactionType string How a payment was made, on payment notifications.
isRead boolean true once marked as read.
createdAt string (date-time) When it was written.
updatedAt string (date-time) When it last changed.
user object The person the notification was written for. Left out when that user no longer exists.
user._id string User id.
user.firstName string First name.
user.lastName string Last name.
user.picture string Profile picture URL, when set.

Example response (Replies to your comments), application/json.

{
  "status": "success",
  "data": {
    "totalCount": 1,
    "totalUnReadCount": 3,
    "notificationList": [
      {
        "_id": "6702b1f0c3a4d5e6f7a8b9c1",
        "mediaId": "d8c2a1f4e5b6",
        "mediaType": "audio",
        "description": "Ana Reviewer replied to your comment on \"Customer call\"",
        "type": "comment",
        "action": "replied",
        "isRead": false,
        "createdAt": "2026-10-07T15:20:00.000Z",
        "updatedAt": "2026-10-07T15:20:00.000Z",
        "user": {
          "_id": "65f0c1a2b3c4d5e6f7a8b9c0",
          "firstName": "Alex",
          "lastName": "Lee"
        }
      }
    ]
  }
}

Mark notifications as read

PUT/notification

Marks every one of your own notifications as read, so totalUnReadCount drops to 0. It takes no body and does not touch anyone else’s notifications.

Example request
curl -X PUT 'https://api.speakai.co/v1/notification' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 Success

Response body, application/json.

Field Type Description
status string success on every 2xx response. One of: success .
message string Confirmation.

Example response (Marked as read), application/json.

{
  "status": "success",
  "message": "Notifications flag is updated successfully."
}

Get an API key on the Speak AI developer page.

Navigation

Get Speak AI

Web PlatformSign in or start free in your browser
Log inStart free
iOS appiPhone and iPadAndroid appPhones and tabletsMCP ServerConnect Claude, ChatGPT and other AI tools
All sections

Type to search…

↑↓ navigate↵ selectEsc close