API Reference

Who this page is for

This section is for developers and technical integrators who want to automate actions in Aimee.ai, connect an AI assistant to your workspace, or build custom tooling on top of the API. If you're a trainer or workspace owner looking to set up notifications or webhooks, see Notifications & Integrations instead.

If you want to use an AI assistant (such as Claude) to help author courses or query workspace data, the Model Context Protocol (MCP) section below is where to start.

The Aimee.ai backend ships an interactive Swagger UI that documents every public API endpoint, including request and response schemas for webhooks and integrations.

Swagger UI

The hosted Swagger UI for the Aimee.ai API is available at:

https://aimee-api.lennonsec.org/apis

You will need a valid bearer token to exercise authenticated endpoints from the Try it out panel. A personal access token is the simplest way to obtain a long-lived one.

Personal access tokens

A personal access token (PAT) lets an external tool, script, or AI assistant call the API as you, with your existing workspace roles - without driving the interactive login flow. Present it exactly like a session token:

Authorization: Bearer aimee_pat_...

Creating a token

1. Open Profile -> Security -> Access tokens and choose Create token.
2. Give it a label, a scope, and an expiry:
3. One workspace - the token only works in the workspace you pick.
4. All my workspaces - valid in every workspace where you are an owner or trainer.
5. Expiry defaults to 90 days (30 / 90 / 365 / no expiry).
6. The token secret is shown once. Copy it immediately and store it somewhere safe - it is never displayed again.

Only workspace owners and trainers can create tokens, and a token is only accepted in a workspace where its owner currently holds one of those roles.

Managing and revoking tokens

• Revoke your own tokens any time under Profile -> Security -> Access tokens.
• A workspace owner or admin can view and revoke every token that can reach their workspace under Workspace Settings -> Integrations -> Access Tokens - a kill switch for a departing member's programmatic access.
• Changing your password or signing out everywhere invalidates all of your tokens.

Treat a token like a password: anyone who holds it can act as you within its scope.

Model Context Protocol (MCP)

Aimee.ai exposes an MCP server so an MCP-capable AI client - for example Claude Code in VS Code - can pull your workspace's course information in as context and act on your behalf: generate a course from a brief, publish it, assign it, or duplicate one.

Connect your client to the workspace endpoint over Streamable HTTP:

https://aimee-api.lennonsec.org/workspaces/<workspaceId>/mcp

Authenticate with a personal access token in the Authorization header, exactly as you would any other API call. The same rules apply: only owners and trainers can connect, the connection works only in the workspace named in the URL, and a token scoped to one workspace cannot reach another.

Turn on MCP access first

MCP access is off by default for every workspace. Before a client can connect, a workspace owner must switch it on in Workspace Settings → Features using the MCP access switch. While it is off, the endpoint is refused even with a valid token. Every tool call an agent makes is recorded in the workspace audit trail, and each token has a per-minute request limit so a runaway agent cannot exhaust the workspace.

Connect and test

There is no separate MCP login - a personal access token is your credential. Follow these four steps once and any MCP client can connect.

1. Turn MCP on. As a workspace owner, switch on MCP access under Workspace Settings → Features - it saves immediately. (Owners and trainers can connect; nobody can while it is off.)
2. Create your token. Follow Creating a token and scope it to the workspace you want the agent to reach. Copy the aimee_pat_... secret - it is shown once.

3. Get your workspace id. The endpoint URL needs your workspace's id (a UUID). It is returned as workspaceId in the response when you create the token; you can also list it any time:

   curl -s https://aimee-api.lennonsec.org/account/access-tokens \
     -H "Authorization: Bearer aimee_pat_..."
   # each token in the list shows the workspaceId it is scoped to
   

4. Test the connection. Send an MCP initialize handshake with curl. A healthy connection returns the server info:

   curl -s https://aimee-api.lennonsec.org/workspaces/<workspaceId>/mcp \
     -H "Authorization: Bearer aimee_pat_..." \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
   

   Expected: {"result":{...,"serverInfo":{"name":"aimee-lms",...}},...}. If instead you get:

   • 401 Unauthorized - the token is missing, wrong, expired, or revoked.
   • 403 Forbidden - MCP is off for the workspace (step 1), or the token owner is not an owner/trainer there.

Once the handshake succeeds, point your MCP client at the same URL. For Claude Code, register it as an HTTP server:

claude mcp add --transport http aimee \
  https://aimee-api.lennonsec.org/workspaces/<workspaceId>/mcp \
  --header "Authorization: Bearer aimee_pat_..."

The client then handles the full handshake for you and lists the tools below. Claude Code can also connect without a token, by signing in through the browser - see Connect Claude (MCP) for the plain-language walkthrough.

Read tools

• list_courses - the courses in the workspace.
• get_course - one course's details.
• get_course_content - a course's published slides as text, to use as grounding context. Unpublished draft content is never exposed.
• get_course_analytics - a course's aggregate completion figures (how many learners are enrolled, in progress, and completed, plus average progress). No individual learner records are shared.
• list_members - the workspace's members and their roles.
• get_generation_status - progress of a course-generation job you started.
• get_workspace_general_settings - the workspace's name, language and other general settings.
• get_workspace_appearance_settings - the workspace's branding and theme.
• get_workspace_ai_config - which AI features are on, and the course length range this workspace allows.
• get_workspace_mcp_settings - the workspace's own MCP access settings.

Each published course is also offered as an attachable resource (aimee-course://<courseId>), so you can add a whole course to your client's context in one step.

One further resource, aimee-model://course-outline, describes how an Aimee course is put together - modules, slides, the kinds of interaction a slide can use, and the size limits. Ask your client to read it before you start planning a course with it, so the plan it drafts fits what Aimee can build.

How fresh a read answer is

Aimee keeps a read answer for a short time and gives the same answer again if your client asks the same question twice. A list answer lasts 30 seconds. A course-content answer lasts 5 minutes. So if you change a course and ask your client about it straight away, your client can still describe the previous version. Ask again a few minutes later to see the change.

Write tools never reuse a held answer, and a held answer never crosses from one workspace to another.

Write tools

Write tools change your workspace, so each one takes a confirm: true argument: called without it, the tool returns a summary of what it would do and makes no change, so an AI agent cannot act by accident. Each also accepts an optional idempotencyKey - repeating a call with the same key returns the first result instead of running twice.

• generate_course - start an AI course, either from a brief or from a plan you have already written. The course pauses at the same review gate as the wizard; nothing becomes a real draft until you approve it.
• approve_generated_course - approve a paused generation and build the full course.
• import_course - create a course from course markdown you already have. This one expects the finished course: every slide's content written out. It is not the way to send an outline - see below. A knowledge-check slide stays in its module as a quiz. Add the line - **Assessment:** final to send it to the end-of-course question pool. Aimee compares each sentence of the markdown with the built course. If a sentence is missing, the import fails and names the slide and the sentence, and no course is created. The result gives the settings that Aimee chose (pass mark, quiz mode, retry limit, number of modules), the counts of slides, blocks and questions, a preview link, a warnings list and a questionsForUser list. The result also gives a fidelity estimate: a score from 0 to 100, the score of each part (text, structure, interactions, images, design, settings) and the findings that lowered it. The score compares the markdown with the course. It does not compare your first source document with the markdown. Each warning names the slide and a correction. Your AI client asks you each question before it reports success. An error tells you if the import left a course behind. The markdown can hold a YouTube block (Slide Type: youtube with a YouTube URL line). The tool cannot receive a file. An Image, Video or Resource block imports only if its File line refers to a file that is already in the workspace. If not, the import skips the block and names it in warnings.
• publish_course - publish a course. The same publish checks as the app apply: anything that blocks publishing is reported back and the course is not published until you fix it.
• assign_course - assign a published course to a learner or a group.
• duplicate_course - copy an existing course into a new editable draft.
• fill_course_images - generate an image for each image placeholder that remains in the draft of a course. One call does a small batch. Your client repeats the call until no placeholder remains.

What a course brief needs

When you ask for a course from a brief, the subject on its own is not enough. Your client has to tell Aimee who the course is for, what you want learners to be able to do afterwards, the difficulty, the tone, and roughly how many slides.

If any of those are missing, the request is refused and your client is told which ones to ask you about. It is not left to pick them for you, because a course built on a guessed audience looks exactly like one built on a real answer - and you would have no way to tell them apart afterwards.

If you would rather take Aimee's standard choices, your client can say so explicitly and the course is built with them.

Sending a written plan as document text needs the same details except the slide count, since your plan already decides that. Sending a full outline needs none of them - the outline already says what every screen is.

Plan a course with your AI client, then send it to Aimee

A common way to work is to think the course through in conversation - what the modules are, what each screen covers, where the questions go - and only bring Aimee in once the plan is settled.

Ask your client to read the aimee-model://course-outline resource first, so it plans within Aimee's structure. Then it sends the plan to generate_course in one of two ways:

• as an outline, when you have the shape of the course but not the words. Aimee writes the content from your plan.
• as document text, when you already have a written plan - one that spells out the narration and the exact quiz answers - and you want it reproduced as written rather than rewritten.

Either way the job stops at the review gate. Your client can then show you the plan exactly as Aimee recorded it, you change anything you want to, and approve_generated_course builds the course. Nothing is generated, and nothing is charged, until you approve. The gate holds for two hours; after that, send the plan again.

Both of these need Outline-driven generation switched on for the workspace, under Workspace Settings > Features.

Connect a remote client with OAuth

A personal access token is the simplest credential for a script or a client you run yourself. For a remote or shared MCP client - a hosted assistant, a teammate's Claude deployment, anything you would rather not hand a long-lived secret - Aimee.ai also supports the standard OAuth 2.1 flow the Model Context Protocol defines for remote servers. The client gets a short-lived token, you approve it with a consent screen, and you can disconnect it any time.

You do not configure any of this by hand. Point an OAuth-capable MCP client at the same workspace URL without a token:

https://aimee-api.lennonsec.org/workspaces/<workspaceId>/mcp

The client then, on its own:

1. Discovers the authorization server from the endpoint (protected-resource and authorization-server metadata).
2. Registers itself automatically (no manual app setup).
3. Opens your browser to an Aimee.ai consent screen. Sign in if you are not already, review which client is asking and for which workspace, and choose Authorize or Deny.

After you authorize, the client receives a short-lived access token (renewed automatically in the background) and connects. The same rules as a token apply: MCP must be switched on for the workspace, the grant covers only that one workspace, and it works only while you hold an owner or trainer role there.

Manage connected apps

Every client you authorize is listed under Profile → Security → Connected apps. Choose Revoke to disconnect one immediately - it loses access at once and must be re-authorized to reconnect. A workspace owner can still cut off access for the whole workspace by turning MCP off, exactly as with tokens.

For a step-by-step walkthrough of this flow with a specific client, see Connect Claude (MCP) or Connect ChatGPT (MCP).

What you will find there

• Every REST endpoint exposed by the backend, grouped by module.
• Request and response shapes, including the JSON payloads used by the CRM Webhooks integration.
• The bearer-auth scheme used by the platform.

Related

• Notifications & Integrations - configuring chat notifications and CRM webhooks
• Workspace Settings - general workspace configuration