Getting Started With OTOH API

Base URL

https://www.otoh.com.br/api/v0

All API v0 routes accept GET only and return JSON, except the audio stream itself.

Authentication

Send your API key in the otoh-api-key header using the Bearer scheme:

otoh-api-key: Bearer YOUR_API_KEY

New API keys use the format OT2.KEY_ID.SECRET. Treat the complete value as a secret.

curl --request GET \
  --url https://www.otoh.com.br/api/v0/projects \
  --header 'accept: application/json' \
  --header 'otoh-api-key: Bearer YOUR_API_KEY'

Do not send the key in a URL, query string, browser storage, logs, analytics, or client-side source code. Use the API from a trusted backend whenever possible.

An expired, revoked, malformed, or unknown key returns 401 Unauthorized.

Scopes and authorized resources

Each key has operation scopes and a list of allowed projects and sensors.

v0:projects:read: list authorized projects and retrieve project details.
v0:data:read: read acoustic measurements from authorized sensors.
v0:events:read: read sound events from authorized sensors.
v0:audio:read: request and download short-lived audio leases; this is required in addition to the Data or Events scope.
v0:embedded-map:read: access an authorized project's embedded map.

A valid key without the required operation scope returns 403 Forbidden.

For Data, Events, and audio, both the project and sensor must be allowed. Unknown or unauthorized IDs return 404 Not found.

Contract period

Data and Events are restricted to the project's contract period. See each endpoint for range and pagination behavior.

Audio

When withAudio=true, the key must have both the endpoint scope and v0:audio:read. Records may include a relative audioUrl and an ISO 8601 audioExpiresAt.

Audio URLs normally expire after 10 minutes and must be requested with the same API key. If a URL expires, repeat the original Data or Events request.

Common responses

400 Invalid request: invalid query parameters or cursor outside the effective contract range.
401 Unauthorized: missing, malformed, expired, revoked, or invalid API key.
403 Forbidden: the key does not include the operation scope required by the route.
404 Not found: unknown or unauthorized resource.
405 Method not allowed: unsupported method.
503 Service unavailable: the request could not be completed safely.

Successful and error responses include Cache-Control: private, no-store, max-age=0.

For support, contact [email protected] and include API DOC in the subject line.