
Send the token on every request:
Authorization: Bearer swa_...
Shown once. Sembly stores only a hash of the token. If you lose it, create a new one. The admin UI shows the last characters of each token so you can tell them apart.
Limits. Up to 5 tokens per workspace. Every token has an expiry of at most 1 year (the UI offers 30, 90, 180 days and 1 year).
Revocation is immediate. Disabling or deleting a token, or disabling the Workspace API, stops the affected calls within seconds.
Rotation. Create a second token, deploy it, check in the request log that the old token is no longer used, then delete the old one. Set a reminder before the expiry date.
Keep tokens on servers. A token gives read access to every meeting of the workspace. Never put it in browser or mobile code, in a repository, or in logs. Store it in your secret manager.
One token per integration makes it easy to see which system made a call and to revoke one without touching the others.
Admins see recent calls in Settings β Automations β Workspace API β Recent API requests: time, endpoint, token, client IP, status and duration, kept for 90 days. Calls refused for a known token (disabled or expired token, IP not allowed, API turned off) are listed with their error code. Calls with a missing or unknown token, or stopped by the per-IP rate limit, are not listed: there is no token to attribute them to.
Every response carries an X-Request-ID header. You can also send your own X-Request-ID (up to 64 characters) and it is echoed back. Quote it when you contact support.
When the allowlist is on, only calls from the listed addresses are accepted. Others get 403 ip_not_allowed.
List the public egress addresses your servers call from: your NAT gateway, firewall or outbound proxy. Internal addresses (10.x, 192.168.x) never reach Sembly and will not match.
Entries are IPv4 or IPv6 addresses or CIDR ranges, for example 203.0.113.7 or 203.0.113.0/28. Up to 50 entries.
Changes apply within seconds. If your egress addresses can change (for example dynamic cloud NAT), reserve static ones first, or calls will start failing with 403.
To find the address Sembly sees, make one call with the allowlist off and check the IP column of the request log.
The per-IP rate limit (see Rate limits and errors) is shared by everything behind one egress address. Several jobs behind one NAT share it.
A token reads the whole workspace. It is not tied to the user who created it.
Included: every meeting of the workspace, including private meetings, uploaded recordings and in-app recordings, in any processing state.
Not included: archived (deleted) meetings, meetings that have not started (scheduled or not scheduled), duplicates, meetings without a recording, and the welcome meeting created for new accounts. Reading one of them by UUID returns 404 meeting_not_found, so a meeting that is archived after you synced it returns 404 too.
Users. GET /users lists every user of the workspace, including deactivated accounts (is_active: false), so that owners and speakers of older meetings can still be resolved.
Never exposed: personal notes, and the internal data Sembly uses to recognize speakers.
Your copy is yours to govern. Data you copy out of Sembly is not covered by Sembly's data retention or deletion. If a meeting is deleted in Sembly, your copy stays until you delete it. Apply your organization's retention and access rules to it.
Every meeting lists accessible_by: the workspace users who have access to it in Sembly.
GET /meetings?accessible_by=<user id> returns only meetings that user can access.
Repeat the parameter to combine users (up to 10). A meeting matches only if all of them have access.
Only workspace users count. Guests outside the workspace never match.
Workspace-wide access in the Sembly app is separate from this list. accessible_by contains only the access record stored on the meeting: the owner and the participants who are workspace users.
A user who can open every meeting in the app matches accessible_by only for meetings where they have an access record.
Find the Sembly user by email: GET /[email protected], and keep the id of the exact email match. URL-encode the email: a + must be sent as %2B.
Cache the mapping from your user to the Sembly user ID. Refresh it daily or when a lookup misses.
List with GET /meetings?status=processed&accessible_by=<id>.
| Meaning | Content |
|---|---|---|
| Recording or processing is still running. |
|
| Processing failed and no content was produced. |
|
| Notes, tasks and transcript are ready. | available |
processed is final unless the meeting is reprocessed internally. Once a meeting is processed, it stays processed, and processed_at does not change.
Reprocessing gives the meeting a new uuid: the old one returns 404 meeting_not_found, and the new one shows up as newly processed when it completes.
Content fields (notes, tasks, transcript) are returned only when you ask for them and only for processed meetings. Otherwise they are null.
Notes and tasks can still change after processing, for example when someone regenerates the notes or edits a task. The API always returns the current version. If you need edits, re-fetch meetings you care about from time to time.
Notes text is HTML.
Use processed_after to pick up meetings as they finish processing.
Keep a checkpoint: a UTC timestamp, stored on your side.
List GET /meetings?status=processed&processed_after=<checkpoint minus 10 minutes>&limit=200 and read every page until has_more is false.
For each meeting, fetch the content you need and upsert it by uuid. The overlap means you see some meetings twice; upserting makes that harmless.
Only after the last page, move the checkpoint to the largest processed_at you saw.
The list is ordered by started_at (newest first), not by processed_at, so take the maximum over all pages rather than the first row.
import requests
from datetime import datetime, timedelta
BASE = "https://api-us.sembly.ai/v1/workspace"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
OVERLAP = timedelta(minutes=10)
def poll(checkpoint: datetime) -> datetime:
since = (checkpoint - OVERLAP).isoformat()
newest, offset = checkpoint, 0
while True:
page = requests.get(f"{BASE}/meetings", headers=HEADERS, params={
"status": "processed", "processed_after": since,
"limit": 200, "offset": offset,
}).json()
for meeting in page["data"]:
upsert_meeting(meeting) # your code; fetch content as needed
processed_at = datetime.fromisoformat(meeting["processed_at"].replace("Z", "+00:00"))
newest = max(newest, processed_at)
if not page["pagination"]["has_more"]:
return newest
offset += 200A poll every 5 to 15 minutes is enough for most uses and costs one or two requests.
Pagination is by offset. If a meeting is archived while you are paging, the following rows move up by one and one meeting can be missed in that run. Once a day, run the same loop with processed_after set to 2 days ago.
Go back in slices, for example one month at a time, with status=processed&started_from=...&started_to=..., and fetch the content of each meeting. Record the time you started the history sync and use it (minus the overlap) as the first polling checkpoint, so meetings processed during the sync are not missed. Plan the time from the rate limits: meeting content is limited to 40 requests per minute per workspace, so 1,000 meetings with one content request each take about 25 minutes.
Two ways to get a transcript:
Inline: GET /meetings/{uuid}?transcript=1 returns the whole transcript in the meeting response. Simple, but long meetings produce a large response.
Paginated: GET /meetings/{uuid}/transcript?limit=2000, then pass next_cursor as cursor until it is null. Default page size 500, maximum 2000. Recommended for long meetings and for processing in chunks. Treat the cursor as opaque.
Before the meeting is processed, the paginated endpoint returns its status and an empty items list.
Items are in spoken order (start, in seconds from the beginning of the recording). is_cross_talk marks speech that overlaps with someone else's.
Each item has a speaker:
{"id": 2, "label": "Alice", "user": {"id": "d39e4ac7-b9e6-4f68-828a-04021e5a1ad4", "email": "[email protected]"}}id groups the utterances of one speaker. It is stable within one meeting only; do not compare it across meetings.
label is always present: the speaker's name, or a generic label such as Speaker 2 when the speaker is unknown.
user is set only when Sembly matched the speaker to a workspace user. Use user.id or user.email to link speakers across meetings.
Ask for gzip (Accept-Encoding: gzip); transcripts compress well.
Every meeting has a web_url, for example https://webapp.sembly.ai/notes/go/meeting/0f87cbfd-c1c7-4734-b307-2be8cdf46210. Use it for an "Open in Sembly" link in your app.
The person who opens it signs in to Sembly and sees the meeting only if they have access to it there. It is not a public share link.
It opens the meeting's main page.
Use the value as returned; do not build the link yourself.
When Sembly joins a meeting from a calendar event, calendar_event tells you which event it was:
"calendar_event": {
"provider": "microsoft",
"ical_uid": "040000008200E00074C5B7101A82E00800000000D0C4A8A2B1F4DC01000000000000000010",
"event_ids": ["AAMkAGI2TG93AAA="],
"series_ids": ["AAMkAGI2TG92AAA="],
"is_recurring": true
}Field | Meaning |
|---|---|
|
|
| The event's iCalendar UID, the same in every attendee's calendar. The main matching key. |
| Provider ids of the event in the calendars Sembly synced. Empty for |
| Provider ids of the recurring series. Empty for a single event. |
|
|
calendar_event is null for uploads, in-app recordings and meetings that were not scheduled from a calendar event.
Single event: its iCalUId equals ical_uid.
Occurrence of a recurring series: ical_uid is the UID of the whole series, because Graph gives each occurrence its own iCalUId. Find the series master, then the occurrence closest to the meeting's started_at:
GET /users/{mailbox}/events?$filter=iCalUId eq '{ical_uid}' returns the series master.
GET /users/{mailbox}/events/{master id}/instances?startDateTime=...&endDateTime=..., with a window of a day around started_at, lists its occurrences.
Pick the occurrence whose start is closest to started_at.
started_at is when Sembly started recording. It can be a few minutes off the scheduled start.
event_ids are Graph event ids. A Graph id is valid only in the mailbox it comes from: each attendee's copy of a meeting has its own id, and the list holds one per calendar Sembly synced. An id can also change when the event is moved to another folder. Use them as a shortcut when you read the same mailbox, and fall back to ical_uid.
Google Calendar. All occurrences of a series share one ical_uid. event_ids holds the occurrence's event id, and series_ids the series id (recurringEventId).
Calendar feeds and email invites. Only ical_uid is set.
A meeting id can change before the meeting is recorded. If Sembly failed to join a meeting scheduled from a calendar event (status: failed) and the event is edited later, the meeting gets a new uuid and a new web_url. The old uuid returns 404 meeting_not_found. Recorded meetings keep their uuid. Use calendar_event.ical_uid to link the new id to the same event.
Counted per calendar minute.
Limit | Requests per minute | Applies to |
|---|---|---|
Per client IP | 300 | Every request from one IP address, checked before the token. A safety limit that normal use stays under |
Per workspace, lists | 120 |
|
Per workspace, meeting content | 40 |
|
Per workspace, transcript pages | 120 |
|
The workspace limits are the ones you normally reach. They are shared by all tokens and all IP addresses of the workspace, so adding tokens or servers does not add capacity. Limits may be tuned during the beta.
A limited request gets 429 rate_limited with a Retry-After header: the seconds until the next minute starts. Wait that long, then continue:
response = requests.get(url, headers=HEADERS, params=params)
if response.status_code == 429:
time.sleep(int(response.headers.get("Retry-After", "60")))
For 5xx responses and network errors, retry with exponential backoff (for example 1, 2, 4, 8 seconds, then give up and alert).
Every error has the same body. Branch on code; message is for humans and may change.
{"error": {"code": "invalid_parameters", "message": "status is invalid."}}
Status |
| Meaning | What to do |
|---|---|---|---|
400 |
| A parameter is missing, malformed or out of range. | Fix the request. Do not retry it unchanged. |
400 |
| The transcript cursor is not valid. | Start again from the first page. |
401 |
| No | Send the token. |
401 |
| Unknown token, a deleted token, or a token from the other region. | Check the token and the base URL. |
401 |
| An admin disabled the token. | Ask an admin to enable it, or use another token. |
401 |
| The token passed its expiry date. | Create a new token. |
403 |
| The Workspace API is turned off for the workspace. | Ask an admin to enable it. |
403 |
| The calling IP is not in the allowlist. | Add your public egress IP. |
403 |
| The workspace plan does not include the API. | Contact Sembly. |
403 |
| The API is not available for this workspace. | Contact Sembly. |
403 |
| The workspace is deactivated. | Contact Sembly. |
404 |
| No such meeting in this workspace, or it was archived. | Treat it as removed. |
404 |
| Unknown URL. | Check the path. |
429 |
| A rate limit was hit. | Wait |
500 |
| Unexpected server error. | Retry with backoff. Quote the |
Datetimes are ISO 8601 in UTC with a Z suffix, and may include fractional seconds, for example 2026-10-27T12:48:18.262653Z. In filters, a datetime without a timezone is read as UTC.
IDs of meetings and users are UUIDs.
Lists use offset (at most 1000000) and limit (default 50, maximum 200) and return pagination.has_more. A larger offset is 400 invalid_parameters.
Unknown query parameters are ignored.
The version is in the path: /v1.
Within v1, changes are additive only: new endpoints, new optional parameters, new response fields, and new values in lists of values such as platform or task type. Write clients that ignore unknown fields and handle unknown values (treat an unknown platform as other).
Breaking changes, such as removing or renaming a field or changing its meaning, go into a new version (/v2), announced in advance. v1 keeps working during the transition.
The OpenAPI document always describes the current contract.
Shortened responses from a test workspace. Lists are cut to one item.
GET /users?limit=2
{
"data": [
{
"id": "270aab1f-d2d6-46f2-a29d-a2fffcc33c0a",
"email": "[email protected]",
"full_name": "Former Employee",
"joined_at": "2026-10-29T12:48:18.595934Z",
"is_active": false
}
],
"pagination": {"offset": 0, "limit": 2, "has_more": true}
}
GET /meetings?status=processed&limit=3
{
"data": [
{
"uuid": "0f87cbfd-c1c7-4734-b307-2be8cdf46210",
"web_url": "<https://webapp.sembly.ai/notes/go/meeting/0f87cbfd-c1c7-4734-b307-2be8cdf46210>",
"title": "Zoom weekly sync",
"started_at": "2026-10-27T12:48:18.262653Z",
"finished_at": "2026-10-27T13:18:18.262653Z",
"duration_seconds": 1800,
"meeting_type": "generic",
"platform": "zoom",
"status": "processed",
"processed_at": "2026-10-28T12:48:18.262653Z",
"owner": {"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "[email protected]"},
"accessible_by": [
{"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "[email protected]"},
{"id": "d39e4ac7-b9e6-4f68-828a-04021e5a1ad4", "email": "[email protected]"},
{"id": "0ce31c4b-c177-43f7-a3b6-e1301a089106", "email": "[email protected]"}
],
"calendar_event": {
"provider": "microsoft",
"ical_uid": "040000008200E00074C5B7101A82E00800000000D0C4A8A2B1F4DC01000000000000000010",
"event_ids": ["AAMkAGI2TG93AAA="],
"series_ids": ["AAMkAGI2TG92AAA="],
"is_recurring": true
}
}
],
"pagination": {"offset": 0, "limit": 3, "has_more": true}
}
GET /meetings/0f87cbfd-c1c7-4734-b307-2be8cdf46210?notes=1&tasks=1
The response has the same fields as a list item, plus:
{
"notes": {
"meeting_type": "generic",
"text": "<h2>Summary</h2><p>The team agreed on the revised site schedule.</p>"
},
"tasks": [
{
"title": "Send the revised schedule",
"description": "Send the revised schedule to the site team",
"type": "task",
"due_date": "2026-11-01",
"raw_timing": "Friday",
"performer": {"label": "Alice", "user": {"id": "d39e4ac7-b9e6-4f68-828a-04021e5a1ad4", "email": "[email protected]"}},
"assigner": {"label": "Pat", "user": {"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "[email protected]"}}
}
],
"transcript": null
}
transcript is null because it was not requested. notes, tasks and transcript are all null for meetings that are not processed.
GET /meetings/0f87cbfd-c1c7-4734-b307-2be8cdf46210/transcript?limit=2
{
"status": "processed",
"items": [
{
"start": 0.0, "end": 1.2, "text": "Let's start with the schedule.", "is_cross_talk": false,
"speaker": {"id": 1, "label": "Pat", "user": {"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "[email protected]"}}
},
{
"start": 0.0, "end": 1.2, "text": "Sure.", "is_cross_talk": true,
"speaker": {"id": 2, "label": "Alice", "user": {"id": "d39e4ac7-b9e6-4f68-828a-04021e5a1ad4", "email": "[email protected]"}}
}
],
"next_cursor": "WzEuNSwzXQ"
}