Public API

Summation’s public REST API (sum-api) — OpenAPI-described access to projects, catalog, queries, reports, files, playbooks, and schedules.

Everything the Addison plugin and the MCP server do runs on Summation’s public REST API:

https://api.summation.com

The contract is the documentation

The live OpenAPI document is the source of truth — routes, schemas, parameters, and examples:

https://api.summation.com/openapi.json

Discover operations from the contract rather than hardcoding paths; the API evolves and operationIds, tags, and schemas are maintained there first.

Authentication

All authenticated endpoints take a bearer token:

Authorization: Bearer <token>

Two ways to get one:

Device login (people)

An RFC 8628 device-authorization flow: request a device login, approve it in the browser, poll for the credential. This is what the Claude plugin’s /addison:signin does for you — if you’re a person using an agent, use the plugin rather than implementing this yourself.

Machine-to-machine (automation)

Your Summation admin issues a client_id and client_secret with scopes. Exchange them for an access token:

curl -X POST https://api.summation.com/v1/auth/m2m/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=agent:read agent:write"

The exchange is form-encoded; all other endpoints use JSON bodies. Access tokens expire (about an hour) — refresh by exchanging again.

What’s available

Area	Typical operations
Projects	list, create, manage catalog entries
Catalog	tables, views, schemas, sample data, lineage
Query	bounded read-only SQL execution
Conversations	chat with Addison (server-sent events)
Reports	generate (SSE), verify, export Markdown/PDF/DOCX
Files	upload, download, import to tables
Connections	create, test, browse data sources
Playbooks & schedules	recurring runs with email delivery

Conventions

• Errors follow a problem-details shape: type, title, status, detail, code, and request_id. Always log the request_id — it joins your failure to server-side traces, and support will ask for it.
• Streaming endpoints (chat, report generation, verification, imports) return server-sent events; send Accept: text/event-stream.
• Pagination fields are documented per-operation in the OpenAPI contract; preserve them rather than assuming page shapes.
• Rate limiting returns 429 — retry with jitter and respect any retry headers.
• Scopes: agent:read for reads, agent:write for mutations, tables:append for file imports. A valid token missing a scope gets 403 with the missing scope named.

Building an agent instead of an app? The MCP Server wraps this API in curated tools with the safety rails already in place — start there.