Rollstack API

• OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
• The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
• An index of the reference: https://docs.rollstack.com/llms.txt

Rollstack is the AI presentation platform for business reporting. Every Rollstack report is a slide deck built from your data, in your own template, and kept current.

The API lets your own code, scripts and AI clients do what you do in the app:

• Find and create reports, import your PowerPoint and Google Slides decks, and ask the slides agent to build and change slides, on brand.
• Add data from any data source:
  • Data warehouses and lakehouses: Snowflake, Databricks, Google BigQuery, Amazon Redshift, Microsoft Fabric, Azure Synapse Analytics, Oracle Autonomous Data Warehouse, Teradata, ClickHouse, DuckDB and more
  • Semantic layers: dbt Semantic Layer, LookML, Snowflake semantic views, Databricks metric views, Cube, AtScale and more
  • BI tools: Power BI, Tableau, Qlik Sense, Looker, ThoughtSpot, Domo, Sigma, Metabase, Amazon QuickSight, Mode, Omni, Hex, Lightdash and more
  • CRMs and business applications: Salesforce, Dynamics 365, HubSpot, SAP, NetSuite, Workday, Zendesk, Gainsight, Google Analytics and more
  • Spreadsheets and files: Excel, Google Sheets, CSV, PDFs, Word, Google Docs, SharePoint, OneDrive, Google Drive, JSON and more
  • Any other application or database through its API
• Refresh reports from their sources. A refresh reruns the same deterministic queries instead of regenerating the report, and uses AI only to repair the calculations and slides the new data broke.
• Create a version of a report for each client, region, team or product line with Bursts.
• Export reports to PowerPoint or PDF.
• Share and schedule reports on any schedule, hourly to yearly or a cron, and email each stakeholder their own version.
• Owners and admins can also manage the organization, its members and its data source connections.

AI assistants such as Claude and ChatGPT can also use Rollstack through its MCP server, included on every plan.

Getting started

1. In Rollstack, open Settings → Connected apps → API keys and create a key with the scopes you need. Copy it: it starts with rsk_ and is shown only once.
2. Send it as a bearer token in the Authorization header of every request.
3. Call GET /me to check the key: it answers the user and organization it belongs to and the scopes it carries.

curl https://api.rollstack.com/public/v1/me \
  -H "Authorization: Bearer rsk_..."

Authentication

An API key acts as the user who created it, in the one organization it was created in, and sees only what that user sees in the app. It never acts with more than the role its user had when they created it, and a key whose user is now a member loses the scopes only owners and admins may grant.

Keys expire on the date set when they were created, if any. A user can revoke their keys in the app at any time, and deactivating a user revokes all of theirs. A missing, unknown, revoked or expired key answers 401.

Scopes

Most endpoints need one scope, shown on their pages, and answer 403 with api-key-missing-scope when the key doesn't carry it; GET /me works with any valid key. Give a key only the scopes it needs. Some endpoints are also limited to owners and admins whatever the scope.

Requests and responses

• Bodies are JSON, except the workbook, document or PowerPoint file a file upload can take as multipart/form-data. Fields an endpoint doesn't accept are rejected rather than ignored.
• Dates are ISO 8601 strings in UTC. Ids are strings, except users', which are numbers.
• GET /reports answers pages of up to limit reports: pass the nextCursor it answers as cursor for the next page, until it is null. Other lists answer every item at once.
• Work that takes a while answers 202 Accepted with an id right away: a message to the slides agent, a run, or a batch of variants added to a burst. Follow it with its GET, and the runs a burst starts with GET /bursts/{id}/runs: each waits up to waitSeconds (20 by default, 30 at most) for the work to finish and answers as soon as it does, so call it again while the status is queued or running.

Errors

Every error answers a JSON body with a stable, machine-readable code and a message for people, such as { "code": "api-key-missing-scope", "message": "This call needs the slide_decks:write scope, which this API key doesn't have. Use a key with it, or connect your AI client to Rollstack again and allow it." }.

Idempotency

A request that times out may have run or not. To retry a write safely, send an Idempotency-Key header with a unique value, such as a UUID, on any POST, PUT, PATCH or DELETE, and send the same value when you retry it. MCP write tools take the same value as their idempotencyKey argument.

curl -X POST https://api.rollstack.com/public/v1/reports \
  -H "Authorization: Bearer rsk_..." \
  -H "Idempotency-Key: 6f1c2a4e-9b7d-4e2f-8a3c-1d5e7f9b0a2c" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly sales"}'

• The first request with a key runs, and its response is kept for 24 hours. A retry with the same key and the same request answers that response, with its status, and runs nothing.
• Keys belong to the API key and the endpoint, so another key or endpoint never sees them. A tool call and a REST request to the same endpoint share them.
• A retry with the same key but a different body, path or query answers 422 idempotency-key-reused. Use a new key for a new request.
• A retry while the first request is still running answers 409 idempotency-key-in-progress: retry it later with the same key. A request that stopped before it answered keeps answering 409 until its key expires, so check whether it took effect before you send it again with a new key.
• A request that fails, such as with a 4xx or 5xx, keeps nothing, so retry it with the same key.
• When keys can't be checked, a request with one answers 503 idempotency-unavailable and runs nothing.
• Without the header, a request runs every time it is sent. GET requests ignore it.

Rate limits

Each API key may make 120 requests a minute. Calls that cost far more than a read have lower limits of their own, counted per user across all their keys and AI clients:

Responses report how much of the key's per-minute limit is left, so a client can slow down before it gets a 429: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds until the minute resets) and RateLimit-Policy. The lower limits above aren't in these headers. Past any limit, calls answer 429 with a Retry-After header: wait that long before calling again, whatever RateLimit-Remaining says. An MCP tool call past any of these limits returns an error result instead, with the rate-limit-exceeded code and a message that says how long to wait.

Versioning

The version is in the path: /public/v1. Changes within v1 only add: new endpoints, new optional request fields, new response fields and new values in fields such as a status or an error code, so ignore fields you don't know and handle values you don't know. An endpoint or field that gets replaced keeps working, and its page says it is deprecated and what replaces it. A change that would break existing calls comes as a new version under a new path, with v1 still running alongside it.

Deprecation and sunset

A deprecated endpoint or field is marked deprecated in the OpenAPI document and on its page, and keeps working for as long as v1 does. When a new version replaces v1, v1 keeps running for at least 12 months after it ships. Through that time, v1 responses carry a Deprecation header with the date v1 was deprecated (RFC 9745) and a Sunset header with the date it stops answering (RFC 8594), and both dates are announced in the product updates.

MCP server

AI clients such as Claude can also use this API as an MCP server: POST JSON-RPC to /public/v1/mcp over Streamable HTTP with the same bearer API key, or sign in with OAuth from a client that supports it. Its tools, named by operationId, find, build, edit, run, export, share, schedule and email reports, upload files and message the slides agent. It lists only the tools the key can call. Everything else, such as deleting reports or managing members or connections, is REST-only.

Connect an AI assistant

Use Rollstack when someone wants a slide deck or report built or kept up to date from their company's data, such as warehouses, BI dashboards and spreadsheets, in their own template, refreshed on a schedule or emailed.

Add the MCP server, https://api.rollstack.com/public/v1/mcp, to the assistant and sign in with Rollstack:

• Claude (claude.ai and the desktop app): in Connectors, add a custom connector with this URL, then Connect. On Team and Enterprise plans an owner adds it in the organization's settings first.
• ChatGPT: Settings → Plugins → MCPs → Add → Add MCP server, with Streamable HTTP and this URL. Save, then Authenticate. On Business and Enterprise plans an admin allows custom servers first.
• Claude Code: claude mcp add --transport http rollstack https://api.rollstack.com/public/v1/mcp, then /mcp to sign in.
• Cursor: add { "mcpServers": { "rollstack": { "url": "https://api.rollstack.com/public/v1/mcp" } } } to ~/.cursor/mcp.json, then sign in when it asks.
• Other clients: send an API key as a bearer token.

Signing in asks the user to approve the scopes the assistant asked for. The assistant can then do what they approved, within their role: a member can't grant the scopes only owners and admins have. Each sign-in creates a key that lasts 90 days and that the assistant refreshes on its own, listed in Settings → Connected apps as a Connected app, where the user can revoke it.

Things to ask it:

• "Build a quarterly business review deck from our Tableau dashboards"
• "Refresh the data in my weekly sales report and email it to the team"
• "Create one deck per region from this template"
• "Schedule the board report to update every Monday"

Endpoints

Reports

• Reports
  • List reports: GET /reports
  • Create report: POST /reports
  • Get report: GET /reports/{id}
  • Update report: PATCH /reports/{id}
  • Delete report: DELETE /reports/{id}
  • Convert report to slide deck: POST /reports/{id}/conversions
  • Duplicate report: POST /reports/{id}/duplicates
  • Transfer ownership: POST /reports/{id}/transfer-ownership
• Templates
  • List templates: GET /templates
  • Import template: POST /templates
  • Update template: PATCH /templates/{templateId}
  • Delete template: DELETE /templates/{templateId}
  • Apply template: POST /reports/{id}/template
• Versions
  • List report versions: GET /reports/{id}/versions
  • Save report version: POST /reports/{id}/versions
  • Restore report version: POST /reports/{id}/versions/{versionId}/restore
• Chat
  • Get slides agent message: GET /reports/{id}/messages/{messageId}
  • Send message to slides agent: POST /reports/{id}/messages
  • Approve slides agent proposal: POST /reports/{id}/messages/{messageId}/replies/{replyId}/approve
  • Cancel slides agent message: POST /reports/{id}/messages/{messageId}/cancel
  • Reject slides agent proposal: POST /reports/{id}/messages/{messageId}/replies/{replyId}/reject
• Memories
  • List memories: GET /memories
  • Add memory: POST /memories
  • Update memory: PATCH /memories/{memoryId}
  • Forget memory: DELETE /memories/{memoryId}
• Runs
  • List report runs: GET /reports/{id}/runs
  • Start report run: POST /reports/{id}/runs
  • Get report run: GET /reports/{id}/runs/{runId}
  • List report syncs: GET /reports/{id}/syncs
  • List runs of all reports: GET /runs
  • Cancel report run: POST /reports/{id}/runs/{runId}/cancel
• Exports
  • Get cloud save: GET /reports/{id}/cloud-export
  • Set cloud save: PUT /reports/{id}/cloud-export
  • Export report: POST /reports/{id}/exports
• Content
  • Get report content: GET /reports/{id}/content
  • Get report design: GET /reports/{id}/design
  • Get slide drafts: GET /reports/{id}/slides/html
  • Get slide images: GET /reports/{id}/slides/images
  • Arrange slides: PATCH /reports/{id}/slides
  • Save draft slides: POST /reports/{id}/slides
  • Change theme: PATCH /reports/{id}/theme
  • Render draft slides: POST /reports/{id}/slides/render
• Uploaded files
  • Get an uploaded file: GET /datasets/{id}
  • Replace an uploaded file: PUT /datasets/{id}
  • Delete an uploaded file: DELETE /datasets/{id}
  • Get a link to upload a file: POST /datasets/uploads
  • Upload a document: POST /documents
  • Upload a file: POST /datasets
• Datasheets
  • Get the data guide: GET /data-guide
  • List report datasheets: GET /reports/{id}/datasheets
  • Add sources to report: POST /reports/{id}/datasheets
  • Get a datasheet: GET /reports/{id}/datasheets/{datasheetId}
  • Remove datasheet from report: DELETE /reports/{id}/datasheets/{datasheetId}
  • Get datasheet data: GET /reports/{id}/datasheets/{datasheetId}/data
  • Add dashboard charts to report: POST /reports/{id}/datasheets/{datasheetId}/elements
  • Preview datasheet changes: POST /reports/{id}/datasheets/changes/preview
  • Query report data: POST /reports/{id}/data/query
  • Save datasheet changes: POST /reports/{id}/datasheets/changes
• Parameters
  • Get report parameters: GET /reports/{id}/parameters
  • Create report parameter: POST /reports/{id}/parameters
  • Update report parameter: PATCH /reports/{id}/parameters/{parameterId}
  • Delete report parameter: DELETE /reports/{id}/parameters/{parameterId}
• Sharing
  • Get report views: GET /reports/{id}/views
  • Share report: PUT /reports/{id}/shares/{userId}
  • Unshare report: DELETE /reports/{id}/shares/{userId}
• Comments
  • List comments: GET /reports/{id}/comments
  • Add comment: POST /reports/{id}/comments
  • Resolve comment thread: POST /reports/{id}/comments/{commentId}/resolve
• Schedules
  • List schedules: GET /reports/{id}/schedules
  • Replace report schedules: PUT /reports/{id}/schedules
• Email
  • List sent emails of all reports: GET /emails
  • Get email settings: GET /reports/{id}/email-config
  • Replace email settings: PUT /reports/{id}/email-config
  • List sent emails: GET /reports/{id}/emails
  • Send email: POST /reports/{id}/emails
  • Send test email: POST /reports/{id}/emails/test
• Bursts
  • List bursts: GET /bursts
  • Create burst: POST /bursts
  • List burst email configurations: GET /bursts/{id}/email-configs
  • Create burst email configuration: POST /bursts/{id}/email-configs
  • Get burst run: GET /bursts/{id}/runs
  • Run burst variants: POST /bursts/{id}/runs
  • Get burst settings: GET /bursts/{id}/settings
  • Update burst settings: PATCH /bursts/{id}/settings
  • List burst variants: GET /bursts/{id}/variants
  • Add burst variants: POST /bursts/{id}/variants
  • Get burst variant batch: GET /bursts/{id}/variants/batches/{batchId}
  • List sync filters: GET /reports/{id}/syncs/{syncId}/filters
  • Send burst email configuration: POST /bursts/{id}/email-configs/{configId}/send
  • Send variant emails: POST /bursts/{id}/variants/emails
  • Rename burst: PATCH /bursts/{id}
  • Delete burst: DELETE /bursts/{id}
  • Set variant email settings: PATCH /bursts/{id}/variants/email-settings
  • Update burst email configuration: PATCH /bursts/{id}/email-configs/{configId}
  • Delete burst email configuration: DELETE /bursts/{id}/email-configs/{configId}
  • Set variant recipients: PUT /bursts/{id}/variants/recipients
  • Update burst filters: PUT /bursts/{id}/filters
  • Reapply burst filters: POST /bursts/{id}/filters/reapply
  • Remove burst variants: POST /bursts/{id}/variants/remove
  • Send burst email configuration test: POST /bursts/{id}/email-configs/{configId}/test

Connections

• Connections
  • List connections: GET /connections
  • Create connection: POST /connections
  • Get connection: GET /connections/{type}/{id}
  • Update connection: PATCH /connections/{type}/{id}
  • Delete connection: DELETE /connections/{type}/{id}
  • Search dashboards: GET /connections/{type}/{id}/dashboards
  • Get dashboard: GET /connections/{type}/{id}/dashboards/{dashboardId}
  • Search models: GET /connections/{type}/{id}/models
  • Search tables: GET /connections/{type}/{id}/tables
  • Replace credentials: PUT /connections/{type}/{id}/credentials
• Connection users
  • List connection users: GET /connections/{type}/{id}/users
  • Add connection users: POST /connections/{type}/{id}/users
  • Suspend connection user: DELETE /connections/{type}/{id}/users/{userId}
• Connection admins
  • Add connection admin: PUT /connections/{type}/{id}/admins/{userId}
  • Remove connection admin: DELETE /connections/{type}/{id}/admins/{userId}
• Spreadsheets
  • Search spreadsheets: GET /spreadsheets
  • Get spreadsheet: GET /spreadsheets/{id}
• SMTP connections
  • List SMTP connections: GET /smtp-connections
  • Create SMTP connection: POST /smtp-connections
  • Delete SMTP connection: DELETE /smtp-connections/{id}

Workspace

• Folders
  • List folders: GET /folders
  • Create folder: POST /folders
  • Get folder: GET /folders/{id}
  • Update folder: PATCH /folders/{id}
  • Delete folder: DELETE /folders/{id}
  • Share folder: PUT /folders/{id}/shares/{userId}
  • Unshare folder: DELETE /folders/{id}/shares/{userId}

Admin

• Organization
  • Get organization: GET /organization
  • Update organization: PATCH /organization
• Members
  • Get current user: GET /me
  • List members: GET /members
  • Update member: PATCH /members/{userId}
  • Deactivate member: POST /members/{userId}/deactivate
  • Reactivate member: POST /members/{userId}/reactivate
• Invites
  • List invites: GET /invites
  • Create invites: POST /invites
  • Delete invite: DELETE /invites/{inviteId}
• LLM provider
  • Get LLM provider: GET /organization/llm-provider
  • Replace LLM provider: PUT /organization/llm-provider
  • Delete LLM provider: DELETE /organization/llm-provider