---
title: "For AI agents"
description: "Instructions for your AI agent to setup API."
url: https://help.sembly.ai/en/articles/212-for-ai-agents
collection: "Workspace API"
updated: 2026-11-16
language: en
---

# For AI agents

Instructions for your AI agent to setup API.

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