From e55ae39cddbb44d5683efd689dc85bdd551f36b1 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Tue, 18 Aug 2026 18:35:42 +0000 Subject: [PATCH] Update OpenAPI specs (v1 + v2) and generated docs - 2026-08-18 18:35:42 [Checksum: 833313f9a4f26c289f7245d6aafcbd6366005b30ba1129d82a177a16a2c78ca7] --- .../meet-workspaces/createMeetWorkspace.mdx | 18 ++++++++---------- .../webhooks/webhook_documentation.mdx | 8 ++++---- openapi-v2.json | 2 +- openapi.json | 4 ++-- 4 files changed, 15 insertions(+), 17 deletions(-) diff --git a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx index 298be72c..ef42743d 100644 --- a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx +++ b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx @@ -24,11 +24,10 @@ _openapi: **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. - 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". - 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. - 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. + 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". + 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. @@ -115,11 +114,10 @@ Create a meet workspace — the parent resource that holds your SAML cert + priv **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. - 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". - 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. - 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. + 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". + 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. diff --git a/content/docs/api/reference/webhooks/webhook_documentation.mdx b/content/docs/api/reference/webhooks/webhook_documentation.mdx index 85386183..7516ccb4 100644 --- a/content/docs/api/reference/webhooks/webhook_documentation.mdx +++ b/content/docs/api/reference/webhooks/webhook_documentation.mdx @@ -48,8 +48,8 @@ _openapi: } ], \"speakers\": [ - \"Jane Smith\", - \"John Doe\" + \"John Doe\", + \"Jane Smith\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", @@ -291,8 +291,8 @@ Sent when a bot successfully completes recording a meeting. Contains full transc } ], \"speakers\": [ - \"Jane Smith\", - \"John Doe\" + \"John Doe\", + \"Jane Smith\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", diff --git a/openapi-v2.json b/openapi-v2.json index e8458688..9a396d30 100644 --- a/openapi-v2.json +++ b/openapi-v2.json @@ -23963,7 +23963,7 @@ ] }, "post": { - "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\". Do not assign the profile yet.\n 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the \"Welcome to Workspace\" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to \"English (United States)\".\n 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow.\n 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", + "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\" and assign the SSO profile to all users.\n 3. Create one or more Workspace users that bots will sign in as, complete the \"Welcome to Workspace\" interactive login for each, and set language to \"English (United States)\".\n 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", "operationId": "createMeetWorkspace", "requestBody": { "content": { diff --git a/openapi.json b/openapi.json index 27baec6e..502d4348 100644 --- a/openapi.json +++ b/openapi.json @@ -378,7 +378,7 @@ "Webhooks" ], "summary": "Webhook Events Documentation", - "description": "Meeting BaaS sends webhook events to your configured webhook URL when specific events occur.\n\n## Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting. Contains full transcription data and a link to the recording.\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"Jane Smith\\\",\n \\\"John Doe\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `complete` event includes:\n- **bot_id**: Unique identifier for the bot that completed recording\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **speakers**: A set of speaker names identified in the meeting\n- **transcript**: Full transcript data with speaker identification and word timing\n- **mp4**: URL to the recording file (valid for 24 hours by default)\n- **event**: Event type identifier (\"complete\")\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting. Contains error details.\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `failed` event includes:\n- **bot_id**: Unique identifier for the bot that failed\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **error**: Error code identifying the type of failure\n- **message**: Detailed human-readable error message\n\nCommon error types include:\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n### 3. `calendar.sync_events`\nSent when calendar events are synced. Contains information about which events were updated.\n```json\n{\n \\\"event\\\": \\\"calendar.sync_events\\\",\n \\\"data\\\": {\n \\\"calendar_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"last_updated_ts\\\": \\\"2023-05-01T12:00:00Z\\\",\n \\\"affected_event_uuids\\\": [\n \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"123e4567-e89b-12d3-a456-426614174002\\\"\n ]\n }\n}\n```\n\nThe `calendar.sync_events` event includes:\n- **calendar_id**: UUID of the calendar that was synced\n- **last_updated_ts**: ISO-8601 timestamp of when the sync occurred\n- **affected_event_uuids**: Array of UUIDs for calendar events that were added, updated, or deleted\n\nThis event is triggered when:\n- Calendar data is synced with the external provider (Google, Microsoft)\n- Multiple events may be created, updated, or deleted in a single sync operation\n- Use this event to update your local cache of calendar events\n\n### 4. `transcription_complete`\nSent when transcription is completed separately from recording (e.g., after retranscribing).\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\nThe `transcription_complete` event includes:\n- **bot_id**: Unique identifier for the bot with the completed transcription\n\nThis event is sent when:\n- You request a retranscription via the `/bots/retranscribe` endpoint\n- An asynchronous transcription process completes after the recording has ended\n\n## Setting Up Webhooks\n\nYou can configure webhooks in two ways:\n1. **Account-level webhook URL**: Set a default webhook URL for all bots in your account using the `/accounts/webhook_url` endpoint\n2. **Bot-specific webhook URL**: Provide a `webhook_url` parameter when creating a bot with the `/bots` endpoint\n\nYour webhook endpoint must:\n- Accept POST requests with JSON payload\n- Return a 2xx status code to acknowledge receipt\n- Process requests within 10 seconds to avoid timeouts\n- Handle each event type appropriately based on the event type\n\nAll webhook requests include:\n- `x-meeting-baas-api-key` header with your API key for verification\n- `content-type: application/json` header\n- JSON body containing the event details\n\n## Webhook Reliability\n\nIf your endpoint fails to respond or returns an error, the system will attempt to retry the webhook delivery. For critical events, we recommend implementing:\n\n- Idempotency handling to prevent duplicate processing of the same event\n- Proper logging of webhook receipts for audit purposes\n- Asynchronous processing to quickly acknowledge receipt before handling the event data\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", + "description": "Meeting BaaS sends webhook events to your configured webhook URL when specific events occur.\n\n## Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting. Contains full transcription data and a link to the recording.\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"John Doe\\\",\n \\\"Jane Smith\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `complete` event includes:\n- **bot_id**: Unique identifier for the bot that completed recording\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **speakers**: A set of speaker names identified in the meeting\n- **transcript**: Full transcript data with speaker identification and word timing\n- **mp4**: URL to the recording file (valid for 24 hours by default)\n- **event**: Event type identifier (\"complete\")\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting. Contains error details.\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `failed` event includes:\n- **bot_id**: Unique identifier for the bot that failed\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **error**: Error code identifying the type of failure\n- **message**: Detailed human-readable error message\n\nCommon error types include:\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n### 3. `calendar.sync_events`\nSent when calendar events are synced. Contains information about which events were updated.\n```json\n{\n \\\"event\\\": \\\"calendar.sync_events\\\",\n \\\"data\\\": {\n \\\"calendar_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"last_updated_ts\\\": \\\"2023-05-01T12:00:00Z\\\",\n \\\"affected_event_uuids\\\": [\n \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"123e4567-e89b-12d3-a456-426614174002\\\"\n ]\n }\n}\n```\n\nThe `calendar.sync_events` event includes:\n- **calendar_id**: UUID of the calendar that was synced\n- **last_updated_ts**: ISO-8601 timestamp of when the sync occurred\n- **affected_event_uuids**: Array of UUIDs for calendar events that were added, updated, or deleted\n\nThis event is triggered when:\n- Calendar data is synced with the external provider (Google, Microsoft)\n- Multiple events may be created, updated, or deleted in a single sync operation\n- Use this event to update your local cache of calendar events\n\n### 4. `transcription_complete`\nSent when transcription is completed separately from recording (e.g., after retranscribing).\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\nThe `transcription_complete` event includes:\n- **bot_id**: Unique identifier for the bot with the completed transcription\n\nThis event is sent when:\n- You request a retranscription via the `/bots/retranscribe` endpoint\n- An asynchronous transcription process completes after the recording has ended\n\n## Setting Up Webhooks\n\nYou can configure webhooks in two ways:\n1. **Account-level webhook URL**: Set a default webhook URL for all bots in your account using the `/accounts/webhook_url` endpoint\n2. **Bot-specific webhook URL**: Provide a `webhook_url` parameter when creating a bot with the `/bots` endpoint\n\nYour webhook endpoint must:\n- Accept POST requests with JSON payload\n- Return a 2xx status code to acknowledge receipt\n- Process requests within 10 seconds to avoid timeouts\n- Handle each event type appropriately based on the event type\n\nAll webhook requests include:\n- `x-meeting-baas-api-key` header with your API key for verification\n- `content-type: application/json` header\n- JSON body containing the event details\n\n## Webhook Reliability\n\nIf your endpoint fails to respond or returns an error, the system will attempt to retry the webhook delivery. For critical events, we recommend implementing:\n\n- Idempotency handling to prevent duplicate processing of the same event\n- Proper logging of webhook receipts for audit purposes\n- Asynchronous processing to quickly acknowledge receipt before handling the event data\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", "operationId": "webhook_documentation", "responses": { "200": { @@ -3502,7 +3502,7 @@ }, "last_updated": { "description": "Timestamp of when this data was generated (in ISO-8601 format)\n\nThis field is maintained for backwards compatibility. It is automatically set to the current time when the response is created.", - "default": "2026-05-27T02:27:30.735912107+00:00", + "default": "2026-08-18T09:35:55.268796029+00:00", "type": "string", "format": "date-time" },