Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Server

Identity and health. Public, so a client can find a server before it has a session.

Paths are relative to /api/v1 on your server.

GET/assistants#

Alexa and Google Home: whether the server listens, and who is linked

P6-48, docs/18. While the assistants.enabled setting is on and the server is claimed by a Collectoh account, it asks collectoh.com for what Alexa and Google Home were told and carries it out on the owner’s own players. links are the assistants linked to it on collectoh.com, as the account service says; empty when it can’t be asked.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/docs#

The API reference

A self-contained reader for this document — one page, no outside resources.

Authorisation
None
  • 200Success. text/html · string
GET/openapi.json#

This document

The OpenAPI 3.1 description of the API, generated from the running server. Public and readable cross-origin.

Authorisation
None
  • 200Success. application/json · object
GET/server/connections#

Where an app can reach this server

For a signed-in app (P6-21, docs/15 §3): the addresses at home, then the public address, then Collectoh Relay when it is switched on. An app asks them all at once, keeps only an answer from this server (id), and uses the relay only when nothing direct answers — chooseConnection in the client SDK does exactly that.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · ServerConnections
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account may not do this. application/json · ErrorEnvelope
GET/server/health#

Report health

Always 200; status is degraded when a dependency is down, because restarting the container would not fix it.

Authorisation
None
  • 200Success. application/json · HealthReport
GET/server/info#

Identify the server

Public and readable cross-origin: a client lists the servers on its network by asking each of them this. Nothing here is secret.

Authorisation
None
  • 200Success. application/json · ServerInfo
  • 503SERVICE_STARTING: the database cannot be reached, so setupComplete cannot be known application/json · ErrorEnvelope