# Ridge Reports API

> Read, write and render reports, run schedules, manage sites and their members, and sign your application's users in to a site.

**Authentication.** Send an API key with each request: `Authorization: Bearer <key>`. Keys are created for a service account on a site's Members page or on the Users page, and can do whatever that account is allowed to do. The Discovery endpoints, which describe this API, need no key.

**Errors.** An error comes back with a message in `error` and, for most errors, a `code` your application can act on. A `404` can also mean that the account has no access.

**Base URL.** `https://ridge.reporting.freshtrack.com/api/v1`. The API document writes each path in full, from `/api/v1`. This file and the specs it links need no API key.

**A first session.**

1. `GET /me` checks the key: it returns the account, the key, and the sites the account is a member of.
2. `GET /sites/{slug}/reports?published=true` lists a site's published reports that the account can read.
3. `GET /sites/{slug}/reports/{report_id}/parameters` says what a report asks for.
4. `POST /sites/{slug}/reports/{report_id}/render` renders it to a file, with the values in `parameters`, keyed by name, and the file type in `format` (`pdf` unless given).

**Writing a report.** A report is written through the account's own draft of it, which nobody else sees: readers keep seeing the published version until the draft is published. The account needs the right to edit the report.

1. Read the report document schema and the expression language, linked below: what a report document holds, and how it computes what it shows.
2. Find the report, or create one: `GET /sites/{slug}/reports?published=false` lists the reports not yet published, and `POST /sites/{slug}/reports` creates a report. `POST /sites/{slug}/reports/import-rdl` creates one from an RDL file, from SQL Server Reporting Services or Bold Reports; its `notes` say what to correct in the draft.
3. `GET /sites/{slug}/reports/{report_id}/draft` returns the document and the draft's `version`, and starts the draft if the account has none.
4. Find the data: `GET /sites/{slug}/data-sources` lists the data sources the account can use, `GET /sites/{slug}/data-sources/{data_source_id}/catalog` lists the tables of one, and `POST /sites/{slug}/reports/{report_id}/draft/sample` tries a query and returns its first rows.
5. `PUT /sites/{slug}/reports/{report_id}/draft/assets/{name}` adds an image, which the document shows as `asset:<name>`.
6. `PUT /sites/{slug}/reports/{report_id}/draft` saves the document. Every change to the draft names the version it is based on as `expected_version`, and answers with the next one. A `409` means the draft changed in the meantime: read it again and reapply the change.
7. `POST /sites/{slug}/reports/{report_id}/draft/render` with `Accept: application/json` renders the draft and returns the file with its `warnings`: each value that could not be evaluated, by its item's `item_id` and the `path` within the item. A draft that cannot run is refused with what is wrong. Correct the document and save it again.
8. Hand the report on. `POST /sites/{slug}/reports/{report_id}/revisions` saves the draft as a named revision, which a person can preview and publish from the report's history. `POST /sites/{slug}/reports/{report_id}/publish` publishes it: do that only when asked to.

For text, prefer the font families `Ridge Sans`, `Ridge Serif` and `Ridge Mono`, which have every weight and the condensed widths.

## Specs

- [API, version 1 (OpenAPI 3.1)](https://ridge.reporting.freshtrack.com/api/v1/specs/api.v1.openapi.json): Every endpoint of this API, with its parameters, request and response bodies, and errors.
- [Report document, version 1 (JSON Schema)](https://ridge.reporting.freshtrack.com/api/v1/specs/report.v1.schema.json): The definition of a report: its page, items, tables, charts, datasets and parameters. A document states the version it follows in `schemaVersion`.
- [Expression language, version 1](https://ridge.reporting.freshtrack.com/api/v1/specs/expr.v1.md): How a report document computes what it shows: the `=` and `{{ }}` forms, types, operators, names, aggregates, format patterns, errors and every function.

## Optional

- [Expression functions, version 1 (JSON)](https://ridge.reporting.freshtrack.com/api/v1/specs/expr.v1.functions.json): Every function of the expression language as data: its signature, parameters, description and examples.
- [API reference](https://ridge.reporting.freshtrack.com/api-docs): The endpoints of the API document, written for people.