> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summation.com/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.

The **[API Reference](/api-reference/projects/list-projects)** section of these docs is generated directly from that document — every endpoint gets a page at `/api-reference/{area}/{operation}` with its parameters, request and response schemas, code samples, and a playground. Because the pages come from the contract rather than being written by hand, they stay in step with the API.

<Card title="Browse the API Reference" icon="code" href="/api-reference/projects/list-projects" horizontal>
  All endpoints, grouped by area — Projects, Tables, Reports, Schedules, Connectors, and more.
</Card>

## 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:login` 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 and `agent:write` for mutations — **file imports are `agent:write`** (`import_file`, `create_table_import`, `create_file_upload`, `write_file_content`). `tables:append` is a separate scope for row appends: `POST`/`PUT /v1/tables/{table_id}/rows`, the ingestion-batch operations, and SumApp register/deregister. 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>