---
title: "Concepts and guides"
description: "Concepts and guides for API tokens."
url: https://help.sembly.ai/en/articles/214-concepts-and-guides
collection: "Workspace API"
updated: 2026-11-16
language: en
---

# Concepts and guides

Concepts and guides for API tokens.

## 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:** 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 /users?email_contains=alice@example.com`, 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

<table data-id="dcd6422c-75a1-43d6-8676-16ad666dd7b2" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p data-id="3d18c683-3d93-45c3-a389-951fb3cbb3da"><code>status</code></p></th><th colspan="1" rowspan="1"><p data-id="8fa0a5c9-f713-402e-b788-25666f45051c">Meaning</p></th><th colspan="1" rowspan="1"><p data-id="fae92022-2968-4afc-b5e3-899b1a06603d">Content</p></th></tr><tr><td colspan="1" rowspan="1"><p data-id="36e295d5-8854-4077-ad7e-163841b11140"><code>in_progress</code></p></td><td colspan="1" rowspan="1"><p data-id="627bf41c-381b-46b1-b50c-e14ad90e5dbe">Recording or processing is still running.</p></td><td colspan="1" rowspan="1"><p data-id="0d008be0-8527-44be-96e6-dd5fe89170d9"><code>null</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="338da268-48c6-4092-b0d4-f1afd4fbc62f"><code>failed</code></p></td><td colspan="1" rowspan="1"><p data-id="2c9b4f35-78b7-4dfe-9807-d37cd4ff9424">Processing failed and no content was produced.</p></td><td colspan="1" rowspan="1"><p data-id="78541547-56dc-4222-8104-a96ebb308422"><code>null</code></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6b0b1b32-316e-4963-838d-a813315e758b"><code>processed</code></p></td><td colspan="1" rowspan="1"><p data-id="28067c93-976b-474d-b70a-59b88cbc532b">Notes, tasks and transcript are ready.</p></td><td colspan="1" rowspan="1"><p data-id="e8dbf268-f7c0-4001-a363-ae50d7076ae5">available</p></td></tr></tbody></table>

-   `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": "alice@example.com"}}
```

-   `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
}
```

<table data-id="b4f5548b-030f-4b96-8a13-29e23567fdbc" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p data-id="c310fd61-dd65-4ce9-b287-7189134a4469">Field</p></th><th colspan="1" rowspan="1"><p data-id="cd6fe2d8-e807-4ea4-970e-6a33179b4d3e">Meaning</p></th></tr><tr><td colspan="1" rowspan="1"><p data-id="b557ef00-d69e-421f-8343-0110c857ac2f"><code>provider</code></p></td><td colspan="1" rowspan="1"><p data-id="77be2b52-7cf4-442c-8ffb-bf09acd061aa"><code>microsoft</code> (Outlook or Microsoft 365 calendar connected in Sembly), <code>google</code> (Google Calendar), <code>ics</code> (calendar feed), <code>email</code> (invite sent to Sembly by email). New values may be added.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="18e34316-b445-4394-8b33-0fa1abaf6059"><code>ical_uid</code></p></td><td colspan="1" rowspan="1"><p data-id="61e6c6fe-baaa-4703-b295-87294c4e8c49">The event's iCalendar UID, the same in every attendee's calendar. The main matching key.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="5507d018-767a-48f3-833f-644f2ea617df"><code>event_ids</code></p></td><td colspan="1" rowspan="1"><p data-id="e6745e09-7ad5-48a0-bb54-4ec2224c253d">Provider ids of the event in the calendars Sembly synced. Empty for <code>ics</code> and <code>email</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="e6ef04d6-e992-4d55-98d0-bde16a9c0eb6"><code>series_ids</code></p></td><td colspan="1" rowspan="1"><p data-id="a60b1617-23e5-4005-bb0a-2cb6a1e47df7">Provider ids of the recurring series. Empty for a single event.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="ef952b82-99e9-44d3-a1f5-42f7003b09b6"><code>is_recurring</code></p></td><td colspan="1" rowspan="1"><p data-id="5b4ef944-1ef2-41b9-a3bb-e8b0c21b68ec"><code>true</code> when the event is part of a recurring series.</p></td></tr></tbody></table>

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

<table data-id="20c6cf65-0cf7-42a7-a455-68fde7db2bb4" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p data-id="7cc2f41a-5fa8-4beb-8d6c-c258850cf669">Limit</p></th><th colspan="1" rowspan="1"><p data-id="74fca580-6de7-4f6d-9249-09c25e8abd1a">Requests per minute</p></th><th colspan="1" rowspan="1"><p data-id="6b7d94a3-3842-490c-8a59-e7d030f35c7e">Applies to</p></th></tr><tr><td colspan="1" rowspan="1"><p data-id="6a351ceb-159b-4acd-9408-3d6a699be65c">Per client IP</p></td><td colspan="1" rowspan="1"><p data-id="a4bfb447-f13e-4b5d-9998-d82471789fc0">300</p></td><td colspan="1" rowspan="1"><p data-id="93fd875f-2b8f-4c9b-84dd-9b636835a5db">Every request from one IP address, checked before the token. A safety limit that normal use stays under</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="436de51f-6576-46b8-97e2-cdfe6874a8b6">Per workspace, lists</p></td><td colspan="1" rowspan="1"><p data-id="951e975b-9fd0-42ee-9baa-d5b6e8d9628d">120</p></td><td colspan="1" rowspan="1"><p data-id="d2ffc585-919a-4439-b09d-8591d2e93d7f"><code>GET /users</code>, <code>GET /meetings</code>, shared by all tokens</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="07dc8ba2-8f89-423e-aefa-c10b1c42ab8d">Per workspace, meeting content</p></td><td colspan="1" rowspan="1"><p data-id="4d13239f-ac28-4dba-a703-6feb2f038286">40</p></td><td colspan="1" rowspan="1"><p data-id="28579e12-7c20-42c9-b240-25902e7a7eae"><code>GET /meetings/{uuid}</code>, shared by all tokens</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="cec115d5-f643-41b8-8c1a-388d174cda9d">Per workspace, transcript pages</p></td><td colspan="1" rowspan="1"><p data-id="4c816d02-2af1-4566-8a02-5811e8576e8b">120</p></td><td colspan="1" rowspan="1"><p data-id="ce19a234-65c3-4f74-a6fc-4ea7509e615a"><code>GET /meetings/{uuid}/transcript</code>, shared by all tokens</p></td></tr></tbody></table>

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."}}

```

<table data-id="ab9f22b1-4d35-4453-a79b-f84805d1d92f" style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p data-id="73383c38-1e25-420a-88a3-79d253c48c08">Status</p></th><th colspan="1" rowspan="1"><p data-id="3b4e8f95-1f72-4837-813b-f8634e0aaf85"><code>code</code></p></th><th colspan="1" rowspan="1"><p data-id="a47e8b76-c957-468f-b57e-c3235474d471">Meaning</p></th><th colspan="1" rowspan="1"><p data-id="7b3e8005-7f7a-42b5-badf-232e42821239">What to do</p></th></tr><tr><td colspan="1" rowspan="1"><p data-id="5290025a-18b1-4c19-8bd1-daf242477be5">400</p></td><td colspan="1" rowspan="1"><p data-id="58a8455d-0346-40d0-8d03-2cde3ca10b0e"><code>invalid_parameters</code></p></td><td colspan="1" rowspan="1"><p data-id="6f2606f1-1e1d-4210-881d-9c9849381bf6">A parameter is missing, malformed or out of range.</p></td><td colspan="1" rowspan="1"><p data-id="902fc17c-0c6c-47f6-b3b5-c7bfba2bb850">Fix the request. Do not retry it unchanged.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="039be073-1032-486a-a68f-3626e5ec0ff0">400</p></td><td colspan="1" rowspan="1"><p data-id="95ae8f03-f116-4e8c-ab9a-f9ab3e262f00"><code>invalid_cursor</code></p></td><td colspan="1" rowspan="1"><p data-id="81f74120-37ec-490c-b2b5-a450b1b9828b">The transcript cursor is not valid.</p></td><td colspan="1" rowspan="1"><p data-id="b60f1b73-7755-49d4-a78a-f4150f66bb10">Start again from the first page.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="8e666ff1-1a93-4a77-b1c5-31d92dd6f052">401</p></td><td colspan="1" rowspan="1"><p data-id="8b443d7f-3d4a-4056-90f1-d171f48b54f6"><code>missing_token</code></p></td><td colspan="1" rowspan="1"><p data-id="620dd0e1-549d-4127-baab-39808c60e374">No <code>Authorization</code> header.</p></td><td colspan="1" rowspan="1"><p data-id="337b90e7-41c0-45be-b731-fea5c9acca51">Send the token.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="fa6f29be-8564-43c6-8cad-986d936d89fb">401</p></td><td colspan="1" rowspan="1"><p data-id="a494219f-63a0-42b7-b91e-30f5ebf9456f"><code>invalid_token</code></p></td><td colspan="1" rowspan="1"><p data-id="f40b75b7-e036-43c4-8f18-6719a15c653f">Unknown token, a deleted token, or a token from the other region.</p></td><td colspan="1" rowspan="1"><p data-id="30c1eb2d-9773-4baf-be03-d2b664c29573">Check the token and the base URL.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="708036dc-8e2b-41b6-a8d6-684e8f34b290">401</p></td><td colspan="1" rowspan="1"><p data-id="a21be752-64ca-4be8-a07d-a0602eca50ad"><code>disabled_token</code></p></td><td colspan="1" rowspan="1"><p data-id="b26be90c-5af1-4305-a7fe-cef4fbd44756">An admin disabled the token.</p></td><td colspan="1" rowspan="1"><p data-id="f93bc0d0-988c-4e71-9e6d-2bb0d44b1bbb">Ask an admin to enable it, or use another token.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6d9c34a3-37b5-4cae-940d-8cf6b1ed3468">401</p></td><td colspan="1" rowspan="1"><p data-id="6fc76509-638c-4406-b8a4-15e265f01d6e"><code>expired_token</code></p></td><td colspan="1" rowspan="1"><p data-id="ad1d935b-f98b-4adb-a767-e1bbd70bcc12">The token passed its expiry date.</p></td><td colspan="1" rowspan="1"><p data-id="0f997856-c3f8-4e3c-873f-d9133a05e6be">Create a new token.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="b879eb8c-de06-4e19-9d46-15dae88ca1fd">403</p></td><td colspan="1" rowspan="1"><p data-id="6e05603b-8ea5-4952-a0e7-e34416d2f9be"><code>api_disabled</code></p></td><td colspan="1" rowspan="1"><p data-id="831bf705-a62c-451e-ae66-ace5935af916">The Workspace API is turned off for the workspace.</p></td><td colspan="1" rowspan="1"><p data-id="c190267e-ba08-4519-a25f-69bbad4aafe9">Ask an admin to enable it.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="bb451520-cf83-4e1a-a5f9-fbf6463ff705">403</p></td><td colspan="1" rowspan="1"><p data-id="b063831b-53b7-4abf-bfd0-0e5d6220b9d6"><code>ip_not_allowed</code></p></td><td colspan="1" rowspan="1"><p data-id="b9fce1fb-2842-4649-a634-285139a61511">The calling IP is not in the allowlist.</p></td><td colspan="1" rowspan="1"><p data-id="5ce64ec9-2129-4e97-85ab-fd359068780d">Add your public egress IP.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="fa5bc87d-5bc8-410f-a097-34e233fc434a">403</p></td><td colspan="1" rowspan="1"><p data-id="0e3079b7-99b2-4375-a81e-4ab6b918dd05"><code>plan_not_allowed</code></p></td><td colspan="1" rowspan="1"><p data-id="9d628bae-22d3-46d4-b9fa-bd41e08e72ca">The workspace plan does not include the API.</p></td><td colspan="1" rowspan="1"><p data-id="d08d1d7e-8a18-442a-9c13-6f33162d32bf">Contact Sembly.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="9e65e9bb-c045-4553-8ae9-242cc77a0848">403</p></td><td colspan="1" rowspan="1"><p data-id="2356cb71-19ed-439e-b557-53ca5cf148a6"><code>workspace_not_eligible</code></p></td><td colspan="1" rowspan="1"><p data-id="55ac408b-b563-4157-807d-4a2415a5dc18">The API is not available for this workspace.</p></td><td colspan="1" rowspan="1"><p data-id="f37c9971-d913-49f9-bef5-2f8cdd68749c">Contact Sembly.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6bf75bbe-918f-4f7c-a8e4-35d856712f3b">403</p></td><td colspan="1" rowspan="1"><p data-id="8efae3fb-1b7d-492d-8541-b113b6a08c2c"><code>workspace_disabled</code></p></td><td colspan="1" rowspan="1"><p data-id="88b0276f-67f4-4499-b420-5d96511dda68">The workspace is deactivated.</p></td><td colspan="1" rowspan="1"><p data-id="0870b83c-8b1f-4f3d-aa7f-a4b7cf277cfc">Contact Sembly.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6d008632-2fc5-41a5-9d25-69e09f1a9d8c">404</p></td><td colspan="1" rowspan="1"><p data-id="763cfda1-45c5-41fc-9d9f-ebba5c1ee9c6"><code>meeting_not_found</code></p></td><td colspan="1" rowspan="1"><p data-id="01102a5d-6621-42b4-8330-77522cd7244f">No such meeting in this workspace, or it was archived.</p></td><td colspan="1" rowspan="1"><p data-id="3469ba84-1d15-43b1-a6aa-9a39be80820b">Treat it as removed.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="d2380194-fd2a-43a6-803f-c60f17db859d">404</p></td><td colspan="1" rowspan="1"><p data-id="12e040f3-7c85-4fe3-8bc3-995a52178ff2"><code>not_found</code></p></td><td colspan="1" rowspan="1"><p data-id="6aaf6222-2dc6-42d7-a72a-e3f5ff452010">Unknown URL.</p></td><td colspan="1" rowspan="1"><p data-id="c4a76dde-adf3-4532-8748-58d22e22eff4">Check the path.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="0d6624f9-eb31-4cd8-8aae-7089c4620e22">429</p></td><td colspan="1" rowspan="1"><p data-id="9d3dc57d-4ca8-4b1a-89ae-471a5a556fe0"><code>rate_limited</code></p></td><td colspan="1" rowspan="1"><p data-id="1e2cd13d-cd7c-4109-9d0e-37a033ca6ff9">A rate limit was hit.</p></td><td colspan="1" rowspan="1"><p data-id="7a844b4b-8157-4e9d-b687-e6f9e4b758a0">Wait <code>Retry-After</code> seconds.</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="0765816a-bad7-4226-bf49-d565d18cd5b4">500</p></td><td colspan="1" rowspan="1"><p data-id="dd907a1d-7a89-483a-a1dd-f16637c2e978"><code>internal_error</code></p></td><td colspan="1" rowspan="1"><p data-id="c5cc58d6-b9b4-4d56-ba6b-9d698bdcb817">Unexpected server error.</p></td><td colspan="1" rowspan="1"><p data-id="8b645351-cfc7-4fce-98bc-b04750c5b810">Retry with backoff. Quote the <code>X-Request-ID</code> if it persists.</p></td></tr></tbody></table>

### 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": "former.employee@example.com",
      "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": "pat@example.com"},
      "accessible_by": [
        {"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "pat@example.com"},
        {"id": "d39e4ac7-b9e6-4f68-828a-04021e5a1ad4", "email": "alice@example.com"},
        {"id": "0ce31c4b-c177-43f7-a3b6-e1301a089106", "email": "bob@example.com"}
      ],
      "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": "alice@example.com"}},
      "assigner": {"label": "Pat", "user": {"id": "82d14ccc-9627-44dc-9469-db84ff79ae3a", "email": "pat@example.com"}}
    }
  ],
  "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": "pat@example.com"}}
    },
    {
      "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": "alice@example.com"}}
    }
  ],
  "next_cursor": "WzEuNSwzXQ"
}
```
