Skip to content

Your first API call

Every call to the Yoshuko API carries your key in one header:

Authorization: Bearer ilk_<prefix>.<secret>

Keep the key out of your code — put it in an environment variable. All examples in these docs read it from YOSHUKO_API_KEY:

export YOSHUKO_API_KEY="ilk_…your key…"

Ask the key who it is

GET /api/v1/agent/whoami/ needs no permission at all. It proves the key works and tells you what it may do, so an agent should call it before anything else.

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


import os
import requests

response = requests.get(
    "https://www-dev.yoshuko.com/api/v1/agent/whoami/",
    headers={"Authorization": f"Bearer {os.environ['YOSHUKO_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())


const response = await fetch("https://www-dev.yoshuko.com/api/v1/agent/whoami/", {
  headers: { Authorization: `Bearer ${process.env.YOSHUKO_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

A working key answers 200:

{
  "org_id": "5b0c9a6e-2f4e-4d8a-9a51-1f3a0c6d2e10",
  "org_name": "Northwind Academy",
  "key_name": "Content agent",
  "scopes": {
    "courses": "edit",
    "chapters": "edit",
    "lessons": "edit",
    "org_settings": "none"
  }
}

scopes is what the key may do right now, per area: none, view (read) or edit (read and change). A person can change these at any time on the API Keys page, so re-check rather than caching them for long.

If it does not work

You get It means Do this
401 Authentication credentials were not provided. The header is missing, or the key is unknown, revoked or expired Check the header spelling and the key; create a new key if needed
401 subscription_inactive The organisation has no active paid plan Subscribe to a plan — see pricing
401 org_unverified The organisation has not finished verification Complete sign-up in the web app
429 More than 300 requests in an hour Wait for the number of seconds in Retry-After

The full list is in Errors and limits.

Next

Build a course with the API — a course, a chapter and a quiz in four calls.