Making requests

The services behind the API

Wiselook is a set of independent services behind a single API gateway. Each owns one domain and exposes an HTTP surface:

Service	Owns
Catalog	Methodologies and competencies: the assessment IP.
Assessment	An assessment run (an evaluation) and its scores.
AI Service	Claire, the AI agent: conducts the conversation (text + voice), owns transcripts.
Tenancy	Organisations (tenants), members, tags, invite codes, widgets, federations.
Identity	Canonical user accounts; the OIDC callback target.

Everything is reached through the gateway. There are two API surfaces:

• Public (/v1/{resource}): what external callers reach (integrator backends, with an OAuth2 client-credentials token, and the widget in a visitor's browser, with a short-lived visitor JWT minted by the integrator's backend).
• Internal (/internal/v1/{resource}): service-to-service only; not issuable to customer credentials.

This documentation covers the public surface. See the API Reference for the per-service endpoint detail.

Base URL and versioning

All public endpoints live under /v1/:

https://<WISELOOK_HOST>/v1/{resource}

The version is at the path root. A breaking change to a resource's contract ships under /v2/; additive changes (new optional fields, new endpoints) stay on /v1/.

Resources

Resource	Service	Example
/v1/methodologies	Catalog	List / read methodologies
/v1/competencies	Catalog	List competencies
/v1/evaluations	Assessment	Create / read assessment runs
/v1/members/{tenant_user_id}/evaluations	Assessment	Start an assessment for a member
/v1/chat/messages	AI Service	Stream a turn from Claire, the AI agent (SSE)
/v1/transcripts/{id}	AI Service	Read a completed transcript
/v1/tenant-users	Tenancy	List / read members and their tags
/v1/access-codes	Tenancy	Create / list / revoke invite codes
/v1/tags	Tenancy	List your tags
/v1/adopted-methodologies	Tenancy	List your adopted methodologies
/v1/widgets/{id}	Tenancy	Widget bootstrap (visitor JWT)
/v1/widgets/{id}/sessions	Tenancy	Mint a visitor JWT for the widget

The API Reference has the full request/response shape for every endpoint.

Error responses

Every error has the same shape:

{
  "code": "snake_case_machine_readable",
  "detail": "Human-readable explanation.",
  "extra": { "any": "structured context" }
}

Branch on code; it's stable across versions. detail is for humans and may change wording. extra carries optional structured context (failing field, conflicting key, current state).

Common codes:

HTTP	code	Meaning
401	http_401	Missing or invalid bearer token.
403	invalid_scope	Token lacks the scope this endpoint requires.
404	http_404	Resource not found (or not visible to your scope).
422	http_422	Request body failed validation.

Idempotency

Write endpoints accept an Idempotency-Key header. Reusing the same key with the same body returns the original result instead of creating a duplicate.