Brightdeck API Reference

1. Endpoint summary

Export downloads additionally use time-limited signed URLs on Google Cloud Storage — see §5.

2. Authentication (OAuth 2.1)

The integration is a public OAuth client (no client secret) using the Authorization Code flow with PKCE (S256, mandatory). Access tokens are Bearer tokens sent as Authorization: Bearer <token> on every API request.

GET /oauth/authorize

Renders a hosted Brightdeck sign-in and consent page. On success the browser is redirected to redirect_uri?code=<code>&state=<state>. Authorization codes are single-use and expire after 5 minutes.

POST /oauth/token

Body is application/x-www-form-urlencoded. Public clients authenticate with a form-encoded client_id and no secret.

Success response (both grants):

{
  "access_token": "<bearer token>",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "<new refresh token>",
  "scope": "presentation:read presentation:write agent:run"
}

• Access tokens live 10 minutes (expires_in: 600).
• Refresh tokens rotate on every refresh — always store the newly returned refresh_token. Unused refresh tokens expire after 30 days. Reusing an already-consumed refresh token revokes the grant, requiring the user to reconnect.
• Failures return HTTP 400 with a JSON body {"code": "oauth.invalid_grant", "message": "..."} (codes: oauth.invalid_request, oauth.invalid_grant, oauth.invalid_scope, oauth.unsupported_grant, oauth.invalid_client).

GET /oauth/userinfo

Bearer-authenticated identity probe; accepts any valid access token regardless of scope. Zapier uses it as the connection test and account label.

{ "sub": "0198f2f3-5a6b-7c8d-9e0f-112233445566", "email": "ada@example.com", "name": "Ada Lovelace" }

Returns 401 with a WWW-Authenticate: Bearer header when the token is missing, invalid, or expired. Any HTTP 401 from the API means the access token should be refreshed and the request retried — the Zapier platform does this automatically.

Scopes

The Zapier integration requests all three.

3. Calling tools (MCP over HTTPS)

All operations are JSON-RPC 2.0 messages POSTed to https://api.brightdeck.ai/mcp/ with headers:

Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

The server is stateless: each request is self-contained, no session ID is issued, and no session termination is required. A tool invocation is this sequence:

1. initialize — negotiate the protocol version (the integration uses 2025-06-18; the server echoes it when supported):

   POST /mcp/
   {"jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "zapier-brightdeck", "version": "1.0.1"}}}

2. notifications/initialized — a notification (no id); the server replies 202. This and later requests include the header MCP-Protocol-Version: <negotiated version>.
3. tools/call — the actual operation:

   POST /mcp/
   {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "deck_create_presentation",
               "arguments": {"prompt": "A 10-slide investor update for Q3", "mode": "yolo"}}}

Responses are either application/json or a text/event-stream body whose single event: message frame carries the same JSON-RPC response. A successful tool result looks like:

{"jsonrpc": "2.0", "id": 2,
 "result": {
   "content": [{"type": "text", "text": "<human-readable summary>"}],
   "structuredContent": { ... }   // typed payload, documented per tool below
 }}

Tool failures set result.isError: true with the message text [error.code] Human-readable message — see §6 for the codes. Both /mcp and /mcp/ are accepted.

4. Tools

All fields below describe each tool’s arguments and its structuredContent result. Timestamps are ISO 8601 with timezone offset. A presentation’s title is its filename field.

The Presentation object

Returned by the list, get, and find operations:

deck_list_presentations

Lists the caller’s presentations, newest first. Backs the New Presentation trigger, the presentation dropdowns, and title search in Find Presentation. Scope: presentation:read.

Result: items (array of Presentation objects), total (integer), skip, limit. Errors: validation.out_of_range.

deck_get_presentation

Fetches one presentation the caller can access. Backs Find Presentation ID lookup. Scope: presentation:read.

Result: a Presentation object. Errors: validation.invalid_format, presentation.not_found.

deck_create_presentation

Starts AI generation of a new deck. Backs Create AI Presentation. Scopes: agent:run and presentation:write. The integration always sends mode: "yolo" (fully automatic generation): the call returns within seconds while slides continue building in the background — poll deck_get_task_status for completion.

Result:

{
  "presentation_id": "0198f2f3-5a6b-7c8d-9e0f-112233445566",
  "view_url": "https://brightdeck.ai/presentations/0198f2f3-...?ai=1",
  "stage": "generating",
  "agent_instructions": "Generation started in the background. ..."
}

Plan-limit refusals are returned as a successful payload with stage: "upgrade_required", a human-readable error, an error_code (billing.quota_exhausted — monthly generation quota used up — or billing.plan_limit, with slide_clamp_info: {requested, cap}), and no presentation_id (nothing was created). The Zapier integration converts these into step errors. Errors: validation.required, validation.out_of_range.

deck_get_task_status

Reports the live state of the AI generation run for a presentation. Backs Get Generation Status. Scope: agent:run.

Errors: validation.invalid (malformed UUID), task.not_found (no generation run exists for this presentation — the Zapier search treats this as “no match”).

deck_export_pptx_url / deck_export_pdf_url

Produces a downloadable PPTX or PDF of a presentation and returns a signed link. Backs Export PPTX / Export PDF. Scope: presentation:read; additionally the caller must hold an editor, admin, or owner role on the presentation.

Result:

{
  "download_url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
  "filename": "Q3 Investor Update.pptx",
  "expires_at": "2026-08-12T18:03:21.512000+00:00",
  "file_size": 2481152
}

download_url expires 60 minutes after issue; file_size is in bytes and may be null. Errors: validation.invalid_format, presentation.not_found, presentation.insufficient_permissions, presentation.file_missing, presentation.download_url_failed; PDF only: presentation.pdf_generation_failed, presentation.pdf_download_url_failed.

deck_share_presentation

Shares a presentation with a person by email. Backs Share Presentation. Scope: presentation:write; the caller must hold an editor-or-higher role, and role grants respect the hierarchy — editors can grant up to editor; admin and owner grants require ownership.

Result: status — one of invitation_sent (recipient has no Brightdeck account yet; the role is granted on signup, with invitation_id set), permission_created (existing user granted access, with a permission summary), or already_has_access (idempotent no-op; the existing role is never changed) — plus email and role. Errors: validation.invalid_format, validation.invalid_value, presentation.not_found, presentation.insufficient_permissions, permission.cannot_grant_role.

5. Downloading export files

The download_url from the export tools is a signed Google Cloud Storage URL. Fetch it with a plain unauthenticated GET — do not send an Authorization header (GCS rejects signed-URL requests that carry one). Links expire 60 minutes after issue; an expired link returns an error status and a new one can be minted by re-running the export tool. The Zapier integration downloads the file at Zap run time and passes it downstream as a file object.

6. Errors

Three layers, in the order a client encounters them:

• HTTP 401 on any api.brightdeck.ai request — access token missing, invalid, or expired. Refresh the token and retry (Zapier does this automatically).
• JSON-RPC error object — malformed request or protocol-level failure.
• Tool errors — result.isError: true with message text [code] Human-readable message:

Billing refusals are not tool errors. deck_create_presentation reports plan limits inside a successful payload (stage: "upgrade_required" with error_code billing.quota_exhausted or billing.plan_limit) so that agent clients can relay them; the Zapier integration converts them into failed Zap steps with the billing message.

Full MCP server documentation: github.com/brightdeck/mcp · Support: support@brightdeck.ai