For AI agents

This page is written for an AI agent (or its developer) deciding whether Yoshuko can do what a user asked, and how to do it. Everything here is also available as plain Markdown: add .md to any page URL, or read /llms.txt.

The short version

Base URL	https://www-dev.yoshuko.com/api/v1/agent/
Auth	Authorization: Bearer ilk_<prefix>.<secret> — one header, no OAuth dance
Format	JSON in, JSON out. Errors are JSON too, with a detail and usually a code
Who gets a key	Any organisation on a paid plan. A person creates it in the web app in about three minutes — guide
Rate limit	300 requests per hour per key; 429 with Retry-After beyond that
Schema	OpenAPI 3: openapi.json
What it can do	capabilities.json — every capability, marked api_key, session or ui

What a key can do today

Resource	Operations	Permission needed
Courses	list, create, read, update, delete	courses view / edit
Chapters (units)	list, create, read, update, delete	chapters view / edit
Lessons, quizzes, assignments	list, create, read, update, delete	lessons view / edit
Organisation settings	read, update	org_settings view / edit
The key itself	read its own organisation and permissions	none

Each key starts with no access and a person grants each permission explicitly — see Key permissions.

What a key cannot do yet

Billing, enrolment, learner progress, analytics and storefront changes are available in the web app but not to an API key today. The capability list marks each one. Plan around them rather than discovering them at run time.

Asking your user for a key

If you are acting for a person, this is the whole request:

To let me manage your Yoshuko courses, please create an API key: open Organization → API Keys → Create key, name it after me, then press Permissions and set Courses, Units (API: chapters) and Lessons to Edit. Copy the key (it is shown only once) and give it to me. Guide with screenshots: https://www-dev.yoshuko.com/docs/get-started/api-key/

Store it where your runtime keeps secrets, and read it from an environment variable — every example in these docs uses YOSHUKO_API_KEY.

First call

curl -sS "https://www-dev.yoshuko.com/api/v1/agent/whoami/" \
  -H "Authorization: Bearer $YOSHUKO_API_KEY"

The response names the organisation and what the key may do — check it before acting:

{
  "org_id": "…",
  "org_name": "Northwind Academy",
  "key_name": "Content agent",
  "scopes": {"courses": "edit", "chapters": "edit", "lessons": "edit", "org_settings": "none"}
}

Next: build a course end to end.

Behaviours to rely on

• No silent overwrites. Editing a lesson requires the updated_at you last read; if a person changed it since, you get 409 stale_lesson with the current version. See Errors and limits.
• Scopes are enforced per request, and revocation is immediate — no grace window.
• Plan limits apply to you exactly as to a person (e.g. the number of courses).
• Every key is visible to its organisation — the API Keys page lists each key's status, expiry and when it was last used, and a person can revoke it at any time.