Getting started

Retorio is an AI coaching platform for enterprise sales, service and leadership teams. The Retorio API lets your systems manage who is in which cohort and receive an event when a coaching user’s result is ready. Your identity provider can handle how those users sign in. Content (programs, trainings and scenarios) is authored by your admins in the Retorio admin app and is not part of the API.

To	Read
Authenticate your system	Authentication
Invite, remove and list users	Cohorts
Receive coaching results	Webhooks
Let users sign in with your identity provider	Single sign-on
Look up an endpoint, its fields and responses	API reference
Generate a client or import the API into a tool	OpenAPI file

Requests

Item	Value
Base URL	https://api.retorio.com/be/v2
Format	JSON over HTTPS, in and out. The one exception is the token spreadsheet: GET /cohorts/{id}/participants with onlyTokens, onlyAvailableTokens and format=xlsx
Body size	At most 10 MB
Rate limit	None published. Batch your calls sensibly
Identifiers	Opaque strings. Store them and pass them back. Do not parse them or match on their shape

Errors

Read the HTTP status first. The body adds detail where there is some.

Status	Meaning
400	The request was refused: it fails validation, or its body is not valid JSON
401	The key is missing, malformed, expired or revoked, the admin who created it was removed, or your organization is deactivated
403	The key’s admin lacks the permission for this call, or, on the cohort calls, your organization does not have the coaching product
404	An identifier in the path does not exist in your organization
413	The request body is larger than 10 MB
415	The Content-Type charset or the Content-Encoding cannot be decoded. Send UTF-8 JSON without a content encoding

The body comes in one of three shapes, so branch on the status rather than on one body schema:

Body	Returned for
message, status, and details where there are specifics	A request that fails validation (400), with details naming what failed. Every 401. A 404
statusCode, message and error	A body that is not valid JSON (400), too large (413) or cannot be decoded (415), and a missing permission (403)
error only	Your organization does not have the coaching product (403)

A 400 from the invitation call:

{
  "details": ["blocked@customer.example"],
  "message": "Request validation failed",
  "status": "INVALID_ARGUMENT"
}

A 401 always has the message unauthenticated, except when the admin who created the key was removed. Then the message says so.

Each operation in the API reference lists the error responses it can return, with their bodies.