Iblai Vibe API

/iblai-vibe-api

First time here? If iblai.env has no ARCHITECTURE=, run /iblai-vibe-start first (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.

Every /iblai-vibe-* skill mounts an SDK component. When none exists for what the user wants, do not build a workaround in the browser — call the platform's REST API from a Next.js route handler with the org's Platform API Token. Everything the platform can do is reachable that way; the iblai-api-* skills (kind api, same repo) document each endpoint (method, URL, body, errors).

Common setup (brand, conventions, env files, verification): see docs/skill-setup.md. Terms: docs/glossary.md.

The one rule

Never prefix the key with NEXT_PUBLIC_, never read it outside server files, never send it to the browser. config.apiKey() returns "" in the browser by design.

Step 1: Install the helper

Render assets/platform.ts.j2 → lib/iblai/platform.ts. It exports:

• platformFetch(path, init?) — server-only fetch against https://api.<DOMAIN> with the Api-Token header, JSON in/out, and a typed PlatformError carrying the platform's status and body.
• verifyCaller(req) — reads the Authorization: Token <dm_token> the browser forwards, calls GET /dm/api/core/token/verify/, and returns the caller's username; null when the token is missing or rejected.
• requireAdmin(req) — verifyCaller plus an org-membership check that the caller is an admin of NEXT_PUBLIC_MAIN_TENANT_KEY (via GET /dm/api/core/platform/users/?platform_key=&query=<username>), or a 401/403 NextResponse.

The browser side sends its token like this (already how vibe-starter's lib/iblai/metadata.ts does it):

const token = localStorage.getItem("dm_token") ?? "";
await fetch("/api/admin/whatever", {
  method: "POST",
  headers: { Authorization: `Token ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

Step 2: Write the route

Render assets/route-example.ts.j2 → app/api/admin/example/route.ts as the pattern to copy: verify the caller, validate the body, call the platform, return its answer, map errors.

Status mapping to keep: platform 401 → your 401; 403 → 403 (not an admin / not allowed); 404 → 404; 429 → 429 (spend cap hit — pass the body through, it names the interval); anything else → 502 with the platform's message.

Three worked examples

A · An admin writes another user's metadata

Only org admins may target &username=<other>; the SDK hook has no such parameter, so it is a server call.

// inside a route handler, after requireAdmin(req)
await platformFetch(
  `/dm/api/core/users/platform-metadata/?platform_key=${org}&username=${encodeURIComponent(target)}`,
  { method: "PATCH", body: { metadata: { role_label: "mentor" }, delete_keys: [] } },
);

Reference: profile-metadata.

B · Create an agent

const agent = await platformFetch<{ unique_id: string }>(
  `/dm/api/ai-mentor/orgs/${org}/users/${caller.username}/mentor-with-settings/`,
  {
    method: "POST",
    body: {
      template_name: "ai-mentor",
      new_mentor_name: name,
      display_name: name,
      description,
      system_prompt: systemPrompt,
    },
  },
);
// agent.unique_id is the UUID every other agent skill needs

Reference: agent-create; the full UI pattern is /iblai-vibe-agent-create.

C · Send a notification to a user

await platformFetch(`/dm/api/notifications/orgs/${org}/send/`, {
  method: "POST",
  body: { username: target, title: "Welcome", body: "Your account is ready." },
});

Confirm the exact path and body in notification before shipping — notification sending is outward-facing; confirm the recipient list with the user first.

Which iblai-api-* skill documents what

They install with the rest of this repo's skills (npx skills add iblai/vibe --all); raw links resolve without installing. The five families most apps read or write are marked ★.

The schema is the contract

Before constructing any URL not copied from a skill, confirm it exists in the live OpenAPI schema:

DOMAIN=$(grep -m1 '^DOMAIN=' iblai.env 2>/dev/null | cut -d= -f2-); DOMAIN=${DOMAIN:-iblai.app}
curl -sS -o /tmp/iblai_schema.yaml "https://api.$DOMAIN/dm/api/docs/schema/"
grep -nE "^  /api/core/users/platform-metadata" /tmp/iblai_schema.yaml

Browsable at https://api.iblai.app/dm/api/docs/. Gateway rule: DM routes are called with the /dm prefix (/api/core/… → /dm/api/core/…); edX routes with /lms.

Verify

1. pnpm typecheck and pnpm test (the helper ships with a unit test in assets/platform.test.ts.j2 → __tests__/platform.test.ts).
2. Exercise the route with a signed-in browser (the token header) — expect 401 without it, 403 as a non-admin, 200 as an admin.
3. Nothing prints the key: grep -rn "IBLAI_API_KEY" app components lib | grep -v "config.apiKey\|process.env.IBLAI_API_KEY" returns nothing.

Related skills

• /iblai-vibe-user-metadata, /iblai-vibe-org-metadata, /iblai-vibe-agent-create — the three common cases, done end to end
• /iblai-vibe-admin — gating admin-only routes and pages
• /iblai-vibe-ops-deploy — the server env (IBLAI_API_KEY) on the hosting platform