> ## Documentation index
> Fetch the complete documentation index at: https://docs.odysseysignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every endpoint of the Odyssey Brand Signal API (API version v1): 15 endpoints, generated from its OpenAPI document.

API versions: v1 (current) https://docs.odysseysignal.com/api/reference.md

The Odyssey Brand Signal API.

A **Signal** is a customer's setup: the **DataSources** it may read. A
DataSource carries one or more **DataSets** (Perception, Conversations,
Visibility). Each DataSet declares its **Metrics** and its **Dimensions** — one
vocabulary used both for filtering and for grouping. Start at `GET /v1/signals`
and follow the links; every DataSet describes itself well enough to be queried
without prior knowledge.

Survey question ids do not appear anywhere in this contract. A metric is
addressed by its key, and whether it is measured per brand is a property of the
metric.

## Base URL and authentication

Base URL: `https://api.odysseysignal.app`. OpenAPI document: https://api.odysseysignal.app/openapi.json

Send an API key in the `X-Api-Key` header, or a bearer token in `Authorization: Bearer <token>`.

## Organizations

- [List organizations](https://docs.odysseysignal.com/api/reference/list-organizations.md): `GET /v1/organizations`. List the organizations behind the Signals this credential reads

## Signals

- [List signals](https://docs.odysseysignal.com/api/reference/list-signals.md): `GET /v1/signals`. List the Signals this credential may read
- [Get signal](https://docs.odysseysignal.com/api/reference/get-signal.md): `GET /v1/signals/{signal_id}`. Describe one Signal, with its DataSources
- [List datasources](https://docs.odysseysignal.com/api/reference/list-datasources.md): `GET /v1/signals/{signal_id}/datasources`. List the DataSources on a Signal
- [Get datasource](https://docs.odysseysignal.com/api/reference/get-datasource.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}`. Describe one DataSource: its type and the DataSets available on it
- [Get dataset](https://docs.odysseysignal.com/api/reference/get-dataset.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}`. Describe one DataSet: its dimensions, period and where its metrics are
- [List entities](https://docs.odysseysignal.com/api/reference/list-entities.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/entities`. List the brands this DataSource carries, by brand list
- [List drivers](https://docs.odysseysignal.com/api/reference/list-drivers.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/drivers`. List the drivers this DataSource is configured with, by brand list
- [List periods](https://docs.odysseysignal.com/api/reference/list-periods.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/periods`. List when this DataSource has data, in total and per DataSet
- [List metrics](https://docs.odysseysignal.com/api/reference/list-metrics.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/metrics`. List the metrics on a DataSet, with their groups
- [Get dimension values](https://docs.odysseysignal.com/api/reference/get-dimension-values.md): `GET /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/dimensions/{dimension_id}/values`. List what a dimension can be filtered to

## Query

- [Run query](https://docs.odysseysignal.com/api/reference/run-query.md): `POST /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/query`. Ask one DataSet a question
- [Run map](https://docs.odysseysignal.com/api/reference/run-map.md): `POST /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/map`. Everything needed to draw one of the DataSet's maps

## Maps

- [Get map guide](https://docs.odysseysignal.com/api/reference/get-map-guide.md): `GET /v1/maps/guide`. How to draw one type of map
- [Get map guide image](https://docs.odysseysignal.com/api/reference/get-map-guide-image.md): `GET /v1/maps/guide/image`. A picture of one type of map, drawn by the reference drawing

## Errors

Errors are `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail` and, for some, more fields that say how to fix the call. The `type` is `https://api.odysseysignal.app/problems/<code>`.

| Status | Code | When |
|---|---|---|
| 400 | `invalid-request` | The request is not valid for this DataSet; `detail` says why. |
| 401 | `unauthorized` | No credential, or one that is not accepted. |
| 403 | `forbidden` | The credential is valid but does not cover what was asked. |
| 404 | `not-found` | Nothing there, or nothing this credential may read. |
| 422 | `validation-failed` | The request does not match the contract; `errors` lists each field. |
| 429 | `rate_limited` | Too many requests, or the monthly quota is used up. |
| 503 | `unavailable` | A service behind the API did not answer; try again. |