API reference
Every endpoint of the Odyssey Brand Signal API (API version v1): 15 endpoints, generated from its OpenAPI document.
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#
Every path below starts at https://api.odysseysignal.app. Send an API key in the X-Api-Key header, or a bearer token in Authorization: Bearer <token>.
The contract as OpenAPI: api.odysseysignal.app/openapi.json
Organizations#
- List organizations
GET /v1
/organizations List the organizations behind the Signals this credential reads
Signals#
- List signals
GET /v1
/signals List the Signals this credential may read
- Get signal
GET /v1
/signals /{signal_id} Describe one Signal, with its DataSources
- List datasources
GET /v1
/signals /{signal_id} /datasources List the DataSources on a Signal
- Get datasource
GET /v1
/signals /{signal_id} /datasources /{datasource_id} Describe one DataSource: its type and the DataSets available on it
- Get dataset
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /datasets /{dataset_id} Describe one DataSet: its dimensions, period and where its metrics are
- List entities
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /entities List the brands this DataSource carries, by brand list
- List drivers
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /drivers List the drivers this DataSource is configured with, by brand list
- List periods
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /periods List when this DataSource has data, in total and per DataSet
- List metrics
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /datasets /{dataset_id} /metrics List the metrics on a DataSet, with their groups
- Get dimension values
GET /v1
/signals /{signal_id} /datasources /{datasource_id} /datasets /{dataset_id} /dimensions /{dimension_id} /values List what a dimension can be filtered to
Query#
Maps#
- Get map guide
GET /v1
/maps /guide How to draw one type of map
- Get map guide image
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. |