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.

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.

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.

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 from a brief. 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.
• 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.

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.

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