API reference

Last updated 2 September 2026.

Five endpoints a service calls, and one it receives. Every call is a POST with a JSON body to https://www.trivela.team, authenticated with your service key as a bearer token. The pages in this section give each one exactly: every field, every status, every error string the handler can produce.

Authorization: Bearer sk_yourservice_…
Content-Type: application/json

Endpoint	What it does
POST /api/link/start	Reserve a link request and get the URL to send the player to.
POST /api/link/redeem	Burn the ticket the player came back with; receive their Trivela identity.
POST /api/link/status	Is this subject linked, what are they shown, and here is what I hold.
POST /api/link/report	Report values for up to 500 subjects at once, on a schedule.
POST /api/link/unlink	End the link from your side.
Webhook	What Trivela sends you when a value a player is shown may have moved.

Responses every endpoint shares

401The Authorization header is missing, malformed, or the key is unknown or revoked.

{ "error": "Unknown or missing service key." }

400The body is not valid JSON.

{ "error": "Expected JSON." }

Every 400 carries a single error string that names the field and the rule. There is never a partial success: on the endpoints that take several values, all are validated before any is applied.

The subject, on every endpoint

subject is your own stable id for the user. Wherever it appears it is checked the same way, in this order, and the first failure is the 400:

subject must be a string.
subject must not be empty.
subject must be at most 255 characters.
subject must not contain control characters.
subject must not have leading or trailing whitespace.

subjectLabel, where it is accepted

Display-only text describing the account being linked. Whitespace is collapsed and trimmed; a blank string becomes null rather than an error.

subjectLabel must be a string when supplied.
subjectLabel must not contain control characters.
subjectLabel must be at most 100 characters.