# iblai/api

> Mirrored from [`iblai/api`](https://github.com/iblai/api) · [`README.md`](https://github.com/iblai/api/blob/main/README.md). This page is generated — edit it in the repository, not here.

Operate any ibl.ai organization from your AI agent. Skills + a chat MCP server.

[Skills](https://skills.sh/iblai/api)
[Claude Code](https://claude.ai)
[Cursor](https://cursor.com)
[GitHub Copilot](https://github.com/features/copilot)
[MCP](https://modelcontextprotocol.io)
[ibl.ai](https://ibl.ai)
[License: MIT](https://github.com/iblai/api/blob/main/LICENSE)

> **Note:** These skills and servers run against the hosted `api.iblai.app` environment. If you'd like a license to the full platform codebase to run locally or self-host, reach out to our team at [ibl.ai/contact](https://ibl.ai/contact).

---

## Quick Start

**Before you start:** you need [Node.js](https://nodejs.org) (for `npx`), a skills-compatible AI agent ([Claude Code](https://claude.ai/code), Cursor, OpenCode, and [15+ others](https://skills.sh)), and an ibl.ai account. **No account yet?** Sign up at [ibl.ai/join](https://ibl.ai/join) — it walks you through creating your own organization.

### 1. Install the skills

```bash
npx skills add iblai/api
```

This installs skills that teach your AI agent how to **drive the ibl.ai platform REST API directly** — configure agents, manage datasets and memory, administer users and roles, send notifications, and pull analytics — for any organization you belong to. You'll now have the `/iblai-api-*` commands in your agent.

### 2. Get signed in

You need an ibl.ai account with your own organization. Two ways in:

- **No account (or no org of your own)?** Go to **[ibl.ai/join](https://ibl.ai/join)**. Signing up creates your account *and* your organization and leaves you logged in — that's everything you need.
- **Already have an account?** Sign in at **[login.iblai.app/me](https://login.iblai.app/me)**.

### 3. Connect it

Run the login skill once. It reads your signed-in session from `login.iblai.app/me`, asks which organization to use, and writes your **org key**, **username**, and a **Platform API Token** to `.env`:

```text
/iblai-api-login
```

Every other skill then reads `IBLAI_ORG`, `IBLAI_USERNAME`, and `IBLAI_API_KEY` from `.env` and calls `https://api.iblai.app` with `Authorization: Api-Token <key>`.

> **Headless / CI? Already have org credentials (key + secret)?** Skip the browser. An **org secret** works directly as the Api-Token — set `IBLAI_ORG=<org key>` and `IBLAI_API_KEY=<org secret>`, then read `IBLAI_USERNAME` from the API (an `is_admin` user on the org). `/iblai-api-login` documents this path under [Fastest path — org credentials](https://github.com/iblai/api/blob/main/skills/iblai-api-login/SKILL.md).

## What is iblai/api

A toolkit for operating the [ibl.ai](https://ibl.ai) platform from your AI agent. Where [`iblai/vibe`](https://github.com/iblai/vibe) gives you UI components to *build* an app, `iblai/api` gives you skills to *run the platform itself* — every agent-configuration and platform-admin operation mapped to its exact REST endpoints (method, URL, body) — plus a hosted MCP server for the one runtime capability that isn't a REST call: chatting with a deployed agent.

**Why it matters:**

- **One skill per operation** — each `/iblai-api-*` skill maps one capability, so changing an agent's LLM or pulling cost analytics is a `/` command, not a docs hunt
- **Any organization** — authenticate once via `login.iblai.app/me`, then target any of your organizations by org key + Api-Token
- **Endpoint-accurate** — skills carry the real `api.iblai.app` request shapes, so your agent calls the platform correctly the first time
- **Runtime chat included** — a hosted Model Context Protocol server for chatting with deployed agents (streamed responses, tool use, RAG) — no local install
- **No UI required** — drive the platform headless, from CI, a terminal, or any MCP-capable assistant

## How It Works

1. **Install** — `npx skills add iblai/api` drops the skills into your project.
2. **Connect** — run `/iblai-api-login` to capture your org + username from `login.iblai.app/me` and store an Api-Token in `.env`.
3. **Operate** — invoke any `/iblai-api-*` skill; it fills in your org, username, and (where relevant) the agent id, then calls `api.iblai.app`.
4. **Automate** — chain skills, or connect the hosted chat MCP server to your assistant to talk to agents at runtime.

## Skills

After installing, use these directly in your AI agent with `/` commands.

### Setup

```text
/iblai-api-login
```

### Agent

```text
/iblai-api-agent-create        /iblai-api-agent-dataset
/iblai-api-agent-setting      /iblai-api-agent-embed
/iblai-api-agent-sandbox       /iblai-api-agent-memory
/iblai-api-agent-access        /iblai-api-agent-history
/iblai-api-agent-llm           /iblai-api-agent-audit
/iblai-api-agent-prompt       /iblai-api-agent-eval
/iblai-api-agent-skill        /iblai-api-agent-chat
/iblai-api-agent-safety        /iblai-api-agent-disclaimer
/iblai-api-agent-privacy       /iblai-api-agent-tool
/iblai-api-agent-mcp           /iblai-api-inference
/iblai-api-agent-session       /iblai-api-agent-support
```

### Organization (platform admin)

```text
/iblai-api-org                 /iblai-api-rbac
/iblai-api-management       /iblai-api-crm
/iblai-api-integration     /iblai-api-notification
/iblai-api-token          /iblai-api-invite
/iblai-api-scim            /iblai-api-billing
/iblai-api-feature
```

### Profile

```text
/iblai-api-profile             /iblai-api-profile-metadata
```

### Content & discovery

```text
/iblai-api-search              /iblai-api-course-create
/iblai-api-analytics           /iblai-api-catalog
/iblai-api-milestone          /iblai-api-credential
/iblai-api-catalog-media       /iblai-api-catalog-invitation
/iblai-api-apply               /iblai-api-external-service-proxy
```

### Platform & ecosystem (non-REST guides)

```text
/iblai-api-infrastructure      /iblai-api-ecosystem
```

### What each skill does

| Skill | Description |
|-------|-------------|
| `/iblai-api-login` | Connect an organization — opens `login.iblai.app/me`, captures org + username + Api-Token into `.env`. Run first. |
| `/iblai-api-agent-create` | Create a new agent from a template (then configure with the other agent skills) |
| `/iblai-api-agent-setting` | Agent identity & capabilities — name, description, category, image, visibility, flags; fork and delete |
| `/iblai-api-agent-sandbox` | Connect/disconnect a sandbox (Claw) instance, push config, run health checks, set the model |
| `/iblai-api-agent-access` | Role-based access to an agent — grant editor / chat / analytics_viewer to users, groups, emails |
| `/iblai-api-agent-llm` | Choose the agent's LLM provider and model |
| `/iblai-api-agent-prompt` | System / proactive / study / guided prompts and suggested-prompt CRUD |
| `/iblai-api-agent-skill` | Browse the skill catalog and assign skills to an agent (requires a sandbox) |
| `/iblai-api-agent-safety` | Moderation & safety systems, prompts/responses, and flagged-prompt logs |
| `/iblai-api-agent-privacy` | Privacy Router — PII detection, redact/mask/block, entity types, output filtering |
| `/iblai-api-agent-disclaimer` | Advisory text and the User Agreement |
| `/iblai-api-agent-tool` | Enable/disable the agent's tools |
| `/iblai-api-agent-mcp` | MCP connectors end to end — register servers, credential connections (org/agent/per-user auth patterns), agent wiring, OAuth connected services, in-chat OAuth events, troubleshooting |
| `/iblai-api-agent-dataset` | Training datasets (RAG) — add files/URLs/YouTube/crawl/GitHub, train, retrain, delete |
| `/iblai-api-agent-embed` | Embed/widget settings + backend token provisioning — CSS/JS, voice, SSO, share links |
| `/iblai-api-agent-memory` | Agent memories and memory categories — list, filter, add, edit, delete |
| `/iblai-api-agent-history` | Conversation history & summaries; export chat history as an async report |
| `/iblai-api-agent-audit` | Agent audit log — who changed what (read-only) |
| `/iblai-api-agent-eval` | Agent evaluations — datasets, experiments, LLM-as-Judge + human scoring, CSV export |
| `/iblai-api-agent-chat` | Set up live chat with an agent — wires the `iblai-api-agent-chat` MCP server into the project |
| `/iblai-api-inference` | Run inference via the OpenAI-compatible API — POST OpenAI-format messages to any `provider/model` (e.g. `openai/gpt-5`) for a completion, SSE stream, or tool calls; list models. Direct REST, no agent needed. |
| `/iblai-api-agent-session` | Talk to a deployed agent directly over REST/SSE (or WebSocket) and manage chat sessions — POST a prompt with attached metadata (`client_context`), list/read sessions and history exports. Direct-transport counterpart to `agent-chat`. |
| `/iblai-api-agent-support` | Human-support tickets escalated from agent chats — list/filter tickets, read the reply thread, respond, change status, close or delete |
| `/iblai-api-org` | Org-wide settings — default agent, help center URL, chat width, feature toggles |
| `/iblai-api-management` | Org admin — Users, Groups, Roles, Policies, Teams, Alerts |
| `/iblai-api-rbac` | RBAC — roles, policies, groups, permission checks, agent/team sharing, student toggles |
| `/iblai-api-crm` | CRM — people, organizations, pipelines, deals (move/won/lost), activities, tags |
| `/iblai-api-integration` | Account integrations — LLM keys, Data Source credentials, API tokens |
| `/iblai-api-token` | Platform API Tokens — list, create (secret shown once), delete |
| `/iblai-api-notification` | Org notifications — counts, inbox, mark-as-read, build & send |
| `/iblai-api-invite` | User invitations — list and send (single or CSV bulk) |
| `/iblai-api-scim` | SCIM 2.0 directory provisioning — users (Enterprise extension), groups, departments, memberships; RBAC group assignment auto-links platforms |
| `/iblai-api-billing` | Billing & credits — credit accounts, item paywalls, prices, checkout (auth + guest), subscriptions, access checks, revenue/subscriber reporting |
| `/iblai-api-feature` | Per-user feature config & flags — get/update (inline or feature+values), bulk-config, apps/onboarding, trial activation, platform provisioning |
| `/iblai-api-profile` | The signed-in user's own profile — Basic, Social, Education, Experience, Resume, Memory |
| `/iblai-api-profile-metadata` | Per-user, per-org metadata key-value store — preferences, settings, feature flags |
| `/iblai-api-search` | Discover agents and content + personalized (RAG) recommendations — faceted search (read-only) |
| `/iblai-api-analytics` | Analytics across agents, content, and users — KPIs, users, topics, transcripts, costs, courses, programs, audit, reports |
| `/iblai-api-course-create` | Course Creation API — generate, edit, and publish courses (tasks, outline, structure) |
| `/iblai-api-catalog` | Learning catalog — courses, programs, pathways, resources, skills/roles taxonomy, enrollment, eligibility, reviews |
| `/iblai-api-milestone` | Catalog milestones — course/resource/program/pathway completions and skill points (block, course, platform, user) |
| `/iblai-api-credential` | Digital credentials — credential CRUD, user/group assignments, assertions, course import/export, provider config (Accredible), analytics |
| `/iblai-api-catalog-media` | Catalog media resources — list/create/update/delete media tied to courses/units/items, multipart upload, search, by-item lookup |
| `/iblai-api-catalog-invitation` | Catalog invitations & licensing — platform/course/program invitations (bulk, blank, redeem), licenses & assignments, access requests, suggestions |
| `/iblai-api-apply` | Application gate — applicant apply/renew/submit flows (drafts, files, fees, withdrawal), reviewer pipeline with per-student decisions, waivers & admin override, placement tests, course assignments, account provisioning, form authoring |
| `/iblai-api-external-service-proxy` | Call third-party AI services (ElevenLabs TTS/voices, HeyGen avatar video) through the External Service Proxy — discover services, POST an envelope to invoke; provider keys stored server-side per org |
| `/iblai-api-infrastructure` | Self-host & deploy the platform (non-REST guide) — AWS single/multi-server architecture, golden-AMI launch pipeline, `iblai-infra-cli` (Terraform + Ansible), edX SSO identity providers, and standing up OpenClaw/NemoClaw sandbox gateway servers |
| `/iblai-api-ecosystem` | Map of the ibl.ai open-source family (non-REST guide) — the five repos (api, vibe, os, lms, infra-cli) + shared `@iblai` tooling: which to reach for when operating vs building vs forking vs deploying, plus the vibe/app-cli app-scaffolding quickstart |

Skills live in [`skills/`](https://github.com/iblai/api/tree/main/skills). Read them, extend them, or write your own.

## Updating the skills

Each skill is one `SKILL.md` that maps an operation to its **exact** `api.iblai.app`
endpoints (method, URL, body). Because the value is endpoint accuracy, edits must be
verified against the real API — not against docs or guesswork. The full contract is in
[`CLAUDE.md`](https://github.com/iblai/api/blob/main/CLAUDE.md); the essentials:

- **Source of truth is the backend URLconf, not the docs.** Only document an endpoint
  if it is registered in the backend repo's `urls.py` (so it actually resolves through
  the gateway). DM skills are derived from `iblai/iblai-dm-pro`;
  app `USAGE.md` files are a starting point but contain errors, gaps, and edX-only
  endpoints that do **not** belong here. Verify each endpoint's method, path, and
  request fields against the actual `urls.py` / views / serializers before shipping.
- **Mind the gateway prefix.** `api.iblai.app` strips a prefix before routing:
  `…/dm/…` → the Data Manager service, `…/edx/…` → Open edX. The prefix is added at the
  gateway, so a backend route like `/api/catalog/courses/` is documented and called as
  `https://api.iblai.app/dm/api/catalog/courses/`. When in doubt, it's a `/dm` endpoint.
- **Keep the canonical structure.** YAML frontmatter (`name`, `description`), then
  `## Auth & conventions` → optional concept section → `## Reads` (GET/HEAD) →
  `## Writes` (POST/PUT/PATCH/DELETE) → `## Example` (one real `curl`) → `## Notes`.
  Multi-resource skills group resources as `###` sub-headings inside Reads/Writes —
  Reads/Writes is always the top-level split. Mark every destructive or outward-facing
  call (delete, send, invite) "confirm with the user first." Material that would bloat the
  primary — exhaustive lookup tables (field schemas, action catalogs) and the developer
  docs' fuller concepts/architecture/guides/troubleshooting — may live in bundled
  `references/*.md` files (and sample files in `assets/`), linked from a `## Reference
  material` section; keep `SKILL.md` the scannable, endpoint-focused primary.
- **Describe APIs, not UIs.** Never reference menus, tabs, buttons, or pages — the
  value is the endpoint, not the screen it used to live behind.
- **Follow the naming + terminology rules.** Skill scope is encoded by prefix
  (`iblai-api-agent-*` = one agent, `iblai-api-profile*` = the signed-in user, bare names =
  org-wide). Use **org / org key** for a customer workspace, not "tenant" or
  "platform" (see the Terminology section in [`CLAUDE.md`](https://github.com/iblai/api/blob/main/CLAUDE.md)).

When a platform endpoint changes, update the affected `SKILL.md` and bump the skill
count badge if you add or remove a skill. Open a PR — see the recent commits for the
verification-first style expected.

## MCP Server

Hosted Model Context Protocol server — no local installation required. This covers the one **runtime** capability the skills can't: actually talking to a deployed agent. Wire it up with **`/iblai-api-agent-chat`** (it writes the config below from your `.env` token + a chosen agent), or add it manually. (Administering the platform is the skills' job — see [Skills vs MCP servers](#skills-vs-mcp-servers).)

| Server | Description | Endpoint |
|--------|-------------|----------|
| iblai-api-agent-chat | Talk to a deployed agent — streamed AI responses (runtime) | `/mcp/agent-chat/` |

### Connect from Claude Code

```bash
claude mcp add iblai-api-agent-chat --transport http https://asgi.data.iblai.app/mcp/agent-chat/ --header "Authorization: Api-Token YOUR_API_TOKEN"
```

### Connect from Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "iblai-agent-chat": {
      "transport": "streamable-http",
      "url": "https://asgi.data.iblai.app/mcp/agent-chat/",
      "headers": {
        "Authorization": "Api-Token YOUR_API_TOKEN"
      }
    }
  }
}
```

### Skills vs MCP servers

The split is **administer/use-via-REST vs chat at runtime**:

- **Skills** do everything you can reach over REST — create and configure agents, manage datasets, memory, users, roles, notifications, discovery/search, recommendations, user profiles and analytics, and reporting — by calling the API directly.
- **The MCP server** is for the one thing that isn't a REST admin call: holding a live conversation with a deployed agent (streamed responses, tool use, RAG).

**Rule: if a skill covers it, there is no server for it.** That's why only `iblai-api-agent-chat` remains — the former `analytics`, `agent-create`, `search`, and `user` servers were removed once skills covered analytics, agent creation, discovery + recommendations (`/iblai-api-search`), and user profile + analytics (`/iblai-api-profile`).

## Authentication

Everything authenticates the same way:

- **Base URL:** `https://api.iblai.app`
- **Header:** `Authorization: Api-Token <key>` on every request
- **Org & username:** from [login.iblai.app/me](https://login.iblai.app/me) — each organization you belong to shows its **key** (e.g. `enterprise`, `iblai`, or a UUID)
- **Api-Token:** `/iblai-api-login` mints your first token from your signed-in session; afterward `/iblai-api-token` lists, creates, and rotates tokens. The secret is shown once.
- **Org credentials (key + secret):** for headless/CI use, an org **secret** is itself a valid Api-Token — set `IBLAI_API_KEY=<org secret>` and `IBLAI_ORG=<org key>` with no browser step. See [Fastest path — org credentials](https://github.com/iblai/api/blob/main/skills/iblai-api-login/SKILL.md).

`/iblai-api-login` does all of this for you — get signed in (via [ibl.ai/join](https://ibl.ai/join) if you're new, or [login.iblai.app/me](https://login.iblai.app/me) if you have an account), then run it and it writes `IBLAI_ORG`, `IBLAI_USERNAME`, and `IBLAI_API_KEY` to `.env`. Never commit `.env` — it is in `.gitignore`.

## Resources

- [skills.sh/iblai/api](https://skills.sh/iblai/api) — install skills with `npx skills add iblai/api`
- [iblai/vibe](https://github.com/iblai/vibe) — companion toolkit for *building* ibl.ai apps (UI components + Claude Code skills)
- [login.iblai.app/me](https://login.iblai.app/me) — your account, organizations, and org keys
- [docs.ibl.ai](https://ibl.ai/docs/os/overview) — platform documentation

## License

MIT — see [LICENSE](https://github.com/iblai/api/blob/main/LICENSE). © [ibl.ai](https://ibl.ai)