> ## Documentation Index
> Fetch the complete documentation index at: https://summation-676748f5-docs-api-and-integrations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
https://api.summation.com
```

## The contract is the documentation

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

```text theme={null}
https://api.summation.com/openapi.json
```

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

## Authentication

All authenticated endpoints take a bearer token:

```text theme={null}
Authorization: Bearer <token>
```

Two ways to get one:

<AccordionGroup>
  <Accordion title="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](/integrations/claude-plugin)'s `/addison:signin` does for you — if you're a person using an agent, use the plugin rather than implementing this yourself.
  </Accordion>

  <Accordion title="Machine-to-machine (automation)">
    Your Summation admin issues a `client_id` and `client_secret` with scopes. Exchange them for an access token:

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  Building an agent instead of an app? The [MCP Server](/integrations/mcp-server) wraps this API in curated tools with the safety rails already in place — start there.
</Note>