Making requests

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/ecos/{id}	Catalog	Read an ECO + its questions
/v1/evaluations	Assessment	Create / read assessment runs
/v1/chat/messages	AI Service	Stream a Claire turn (SSE)
/v1/transcripts/{id}	AI Service	Read a completed transcript
/v1/widgets/{id}	Tenancy	Widget bootstrap
/v1/widgets/{id}/sessions	Tenancy	Mint a visitor JWT

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.