company logo

Help center

Contact Support Team
Sembly πŸ‡ΊπŸ‡ΈSembly πŸ‡ͺπŸ‡Ί
All collectionsHow-to ArticlesWorkspace APIConcepts and guides

Concepts and guides

Concepts and guides for API tokens.

Inna KhomaΒ·November 16, 2026

Authentication and tokens

Send the token on every request:

JavaScript
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.

Request log

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.

IP allowlist

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.

Scope and data

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.

Who can see a meeting: accessible_by

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.

warning icon
accessible_by is a filter, not an authorization check. The token can read every meeting. If your app shows meetings to its own users, your app decides what each user may see, for example, by always filtering with that user's ID.
  • 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.

Recipe: show a user their meetings

  1. 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.

  2. Cache the mapping from your user to the Sembly user ID. Refresh it daily or when a lookup misses.

  3. List with GET /meetings?status=processed&accessible_by=<id>.

Statuses and when content is available

status

Meaning

Content

in_progress

Recording or processing is still running.

null

failed

Processing failed and no content was produced.

null

processed

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.

Polling for new meetings

Use processed_after to pick up meetings as they finish processing.

  1. Keep a checkpoint: a UTC timestamp, stored on your side.

  2. List GET /meetings?status=processed&processed_after=<checkpoint minus 10 minutes>&limit=200 and read every page until has_more is false.

  3. 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.

  4. 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.

Python
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 += 200

A poll every 5 to 15 minutes is enough for most uses and costs one or two requests.

Daily reconciliation

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.

First sync of history

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.

Transcripts and speakers

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:

JSON
{"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.

Links to Sembly and calendar events

Open a meeting in Sembly

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.

Match meetings with calendar events

When Sembly joins a meeting from a calendar event, calendar_event tells you which event it was:

JSON
"calendar_event": {
  "provider": "microsoft",
  "ical_uid": "040000008200E00074C5B7101A82E00800000000D0C4A8A2B1F4DC01000000000000000010",
  "event_ids": ["AAMkAGI2TG93AAA="],
  "series_ids": ["AAMkAGI2TG92AAA="],
  "is_recurring": true
}

Field

Meaning

provider

microsoft (Outlook or Microsoft 365 calendar connected in Sembly), google (Google Calendar), ics (calendar feed), email (invite sent to Sembly by email). New values may be added.

ical_uid

The event's iCalendar UID, the same in every attendee's calendar. The main matching key.

event_ids

Provider ids of the event in the calendars Sembly synced. Empty for ics and email.

series_ids

Provider ids of the recurring series. Empty for a single event.

is_recurring

true when the event is part of a recurring series.

calendar_event is null for uploads, in-app recordings and meetings that were not scheduled from a calendar event.

Outlook and Microsoft 365 (Microsoft Graph)

  • 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:

    1. GET /users/{mailbox}/events?$filter=iCalUId eq '{ical_uid}' returns the series master.

    2. GET /users/{mailbox}/events/{master id}/instances?startDateTime=...&endDateTime=..., with a window of a day around started_at, lists its occurrences.

    3. 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.

Rate limits and errors

Rate limits

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

GET /users, GET /meetings, shared by all tokens

Per workspace, meeting content

40

GET /meetings/{uuid}, shared by all tokens

Per workspace, transcript pages

120

GET /meetings/{uuid}/transcript, shared by all tokens

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:

Python
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).

Errors

Every error has the same body. Branch on code; message is for humans and may change.

JSON
{"error": {"code": "invalid_parameters", "message": "status is invalid."}}

Status

code

Meaning

What to do

400

invalid_parameters

A parameter is missing, malformed or out of range.

Fix the request. Do not retry it unchanged.

400

invalid_cursor

The transcript cursor is not valid.

Start again from the first page.

401

missing_token

No Authorization header.

Send the token.

401

invalid_token

Unknown token, a deleted token, or a token from the other region.

Check the token and the base URL.

401

disabled_token

An admin disabled the token.

Ask an admin to enable it, or use another token.

401

expired_token

The token passed its expiry date.

Create a new token.

403

api_disabled

The Workspace API is turned off for the workspace.

Ask an admin to enable it.

403

ip_not_allowed

The calling IP is not in the allowlist.

Add your public egress IP.

403

plan_not_allowed

The workspace plan does not include the API.

Contact Sembly.

403

workspace_not_eligible

The API is not available for this workspace.

Contact Sembly.

403

workspace_disabled

The workspace is deactivated.

Contact Sembly.

404

meeting_not_found

No such meeting in this workspace, or it was archived.

Treat it as removed.

404

not_found

Unknown URL.

Check the path.

429

rate_limited

A rate limit was hit.

Wait Retry-After seconds.

500

internal_error

Unexpected server error.

Retry with backoff. Quote the X-Request-ID if it persists.

Conventions

  • 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.

Versioning

  • 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.

Example responses

Shortened responses from a test workspace. Lists are cut to one item.

Users

GET /users?limit=2

JSON
{
  "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}
}

Meetings

GET /meetings?status=processed&limit=3

JSON
{
  "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}
}

One meeting with content

GET /meetings/0f87cbfd-c1c7-4734-b307-2be8cdf46210?notes=1&tasks=1

The response has the same fields as a list item, plus:

JSON
{
  "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.

Transcript page

GET /meetings/0f87cbfd-c1c7-4734-b307-2be8cdf46210/transcript?limit=2

JSON
{
  "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"
}

Did this answer your question?
😞
😐
😁