company logo

Help center

Contact Support Team
Sembly πŸ‡ΊπŸ‡ΈSembly πŸ‡ͺπŸ‡Ί
All collectionsHow-to ArticlesWorkspace APIFor AI agents

For AI agents

Instructions for your AI agent to setup API.

Inna KhomaΒ·November 16, 2026

Copy the block below into the instructions of your coding assistant or AI agent (for example a rules file, a system prompt or an llms.txt). Optionally, link this page to let agent explore the documentation.

It is a compact summary; the OpenAPI document and current documentation page stays the source of truth for fields and parameters.

markdown
# Sembly Workspace API (v1): agent guide

Read-only REST API over the meetings of one Sembly workspace. Server-to-server only.

## Basics
- Base URL: https://api-us.sembly.ai/v1/workspace (US) or https://api-eu.sembly.ai/v1/workspace (EU). A token works only in its own region.
- OpenAPI 3.1 spec (source of truth for fields and parameters): {base}/openapi.json
- Auth: header `Authorization: Bearer swa_...` on every request. Never log the token or send it to a browser.
- Datetimes: ISO 8601, UTC, `Z` suffix, may have fractional seconds. Filter values without a timezone are read as UTC.
- Ignore unknown response fields and unknown enum values (treat an unknown `platform` as `other`).

## Endpoints
- GET /users: workspace users, including deactivated (`is_active: false`). Filters: `id` (user id), `email_contains`. Paging: `offset` (max 1000000), `limit` (default 50, max 200).
- GET /meetings: meetings, newest `started_at` first. Filters: `status` (`processed`, `in_progress`, `failed`), `started_from`, `started_to`, `processed_after` (strictly after), `owner`, `title_contains`, `accessible_by` (repeatable, max 10, AND). Paging: `offset` (max 1000000), `limit` (default 50, max 200); response has `pagination.has_more`. Each meeting has `web_url` (opens it in the Sembly web app; needs a Sembly login) and `calendar_event` (null when the meeting did not come from a calendar).
- GET /meetings/{uuid}: one meeting. Add `notes=1`, `tasks=1`, `transcript=1` for content. Content is null unless `status` is `processed`. Notes `text` is HTML.
- GET /meetings/{uuid}/transcript: paginated transcript. `limit` (default 500, max 2000) and opaque `cursor`; follow `next_cursor` until null. Before processing: `status` plus empty `items`.

## Rules
- `processed` is final unless the meeting is reprocessed; `processed_at` never changes once set. Reprocessing gives the meeting a new `uuid` (the old one returns 404).
- `uuid` does not change once a meeting is recorded. A `failed` meeting scheduled from a calendar event can get a new `uuid` when the event is edited.
- Calendar matching: compare `calendar_event.ical_uid` with the event's iCalendar UID. For a recurring Microsoft series it is the UID of the series: pick the occurrence whose start is closest to `started_at`. Microsoft `event_ids` are valid only in their own mailbox.
- `accessible_by` is a filter, not an authorization check. The token reads the whole workspace; the calling app decides what each of its users may see. The list is the access items stored on the meeting (owner and workspace participants). Workspace-wide access in the Sembly app is not included.
- Speaker `id` is stable within one meeting only. Use `speaker.user.id` or `speaker.user.email` across meetings; `user` is null when not matched.
- Not listed: archived, welcome, scheduled, not scheduled and duplicate meetings, and meetings without a recording. Archived meetings disappear: `GET /meetings/{uuid}` returns 404 `meeting_not_found`. Treat it as removed.

## Polling recipe
1. Keep a UTC checkpoint.
2. GET /meetings?status=processed&processed_after={checkpoint - 10 min}&limit=200, reading every page until `has_more` is false.
3. Upsert each meeting by `uuid` (overlap causes duplicates; upsert makes them harmless) and fetch content as needed.
4. After the last page, set the checkpoint to the max `processed_at` seen (the list is not ordered by `processed_at`).
5. Once a day, rerun with `processed_after` = now - 2 days to catch rows skipped by offset paging.

## Limits and retries
- Per client IP: 300 requests/min across all endpoints (a flood guard, above the workspace limits).
- Per workspace, shared by all tokens: lists 120/min, GET /meetings/{uuid} 40/min, transcript pages 120/min.
- Windows are calendar minutes. On 429 `rate_limited`, sleep `Retry-After` seconds, then continue.
- On 5xx or network errors, retry with exponential backoff (1, 2, 4, 8 s), then fail.
- Do not retry 400, 401 or 403 unchanged.

## Errors
Body: {"error": {"code": "...", "message": "..."}}. Branch on `code`, not `message`. Every response has `X-Request-ID`.
- 400: invalid_parameters, invalid_cursor (restart transcript paging)
- 401: missing_token, invalid_token, disabled_token, expired_token
- 403: api_disabled, ip_not_allowed, plan_not_allowed, workspace_not_eligible, workspace_disabled
- 404: meeting_not_found, not_found
- 429: rate_limited
- 500: internal_error (retry with backoff)

Did this answer your question?
😞
😐
😁