# mobieusCore API — Overview

The mobieusCore REST API is your tenant's programmatic surface. Use it to read events, list users and posts, manage webhook endpoints, read the marketplace, files, and moderation queue, act on reports, manage the full helpdesk surface (tickets, queues, canned responses, tags, AI hooks), author mobieusLearn courses + enrollments + certificates, and read or write mobieusKnow wiki pages.

## Plan availability

The public REST API is available on **Pro**, **Creator Plus**, and **Sovereign** plans. Tenants on Starter get `403 plan_gated` on every API call with the current and required plans in the error envelope. Upgrade in **`/admin/billing`**.

## The shape of the API

- **REST + JSON**: GETs read, POSTs change.
- **Bearer auth**: `Authorization: Bearer mc_live_...`
- **Per-tenant**: every endpoint lives on your tenant subdomain (e.g. `https://YOUR-TENANT.mobieus.io/api/v1/...`). A key from tenant A literally cannot read tenant B.
- **Cursor-paginated** lists: pass `?cursor=...&limit=N` (max 100). `next_cursor: null` means there's nothing more.
- **Response envelope** is always `{"data": ..., "next_cursor": ..., "request_id": "req_..."}`.

## Surfaces

| Surface | Resources | Scopes | Guide |
|---|---|---|---|
| **Core** | events, users, posts, listings, files, reports, moderation, webhooks | `events:read`, `users:read`, `posts:read`, `listings:read`, `files:read`, `reports:read`, `reports:manage`, `moderation:read`, `webhooks:read`, `webhooks:manage` | this page |
| **mobieusHelp** | tickets, queues, agents, canned responses, tags, help topics, notification prefs, audit, 8 AI hooks | `helpdesk:read`, `helpdesk:write`, `helpdesk:admin` | [api-helpdesk](api-helpdesk) |
| **mobieusLearn** | courses, modules, lessons, activities, enrollments, attempts, certificates, certificate templates, SCORM packages | `learn:read`, `learn:write` | [api-learn](api-learn) |
| **mobieusKnow** | wiki pages, revisions, search | `know:read`, `know:write` | [api-knowledge](api-knowledge) |

## Current version: 1.3.0

| Version | Date | What |
|---|---|---|
| **1.3.0** | 2026-06-02 | mobieusLearn (25 endpoints), mobieusKnow (10 endpoints), mobieusHelp Phase 2 + 8 AI hooks (22 endpoints). 5 new scopes. |
| 1.2.0 | 2026-05-29 | mobieusHelp tickets / queues / agents / reply / status (read + write). |
| 1.1.0 | 2026-05-28 | Webhooks (HMAC-signed delivery + replay + rotate). Listings + files + reports + moderation. |
| 1.0.0 | 2026-05-27 | Events, users, posts (read-only). |

The full machine-readable spec is at `/docs/api/openapi.yaml` in your tenant. The Redoc viewer is at `/api/docs`.

## Quick start

1. Generate a key at **`/admin/api-keys`**. Pick the smallest scope set that covers your use case.
2. Pass it as a bearer token: `Authorization: Bearer mc_live_...`.
3. Hit any GET endpoint to verify:

```bash
curl https://YOUR-TENANT.mobieus.io/api/v1/events \
  -H 'Authorization: Bearer mc_live_...'
```

## Authentication, scopes, rate limits

- **`api-authentication`** covers key minting, scope enforcement, rotation, per-key rate limits (60 / minute, 1000 / hour by default), and the error envelope.

## Webhooks

- **`api-webhooks-quickstart`** covers HMAC signature verification, replay protection, and the delivery dashboard.

## Per-surface guides

- **`api-events-reference`** — event types fired by the platform.
- **`api-marketplace-files-moderation`** — listings, files, and the moderation queue.
- **`api-helpdesk`** — full helpdesk surface (tickets, queues, canned responses, tags, AI hooks).
- **`api-learn`** — mobieusLearn courses, enrollments, certificates, SCORM.
- **`api-knowledge`** — mobieusKnow pages + revisions + search.

## Common errors

| HTTP | Code | When |
|---|---|---|
| 401 | `invalid_api_key` | No `Authorization` header, or the bearer key isn't recognised. |
| 403 | `insufficient_scope` | Key is missing the scope this endpoint requires. The body's `extra.required_scope` tells you which one to add. |
| 403 | `plan_gated` | Tenant plan doesn't include the public API. Upgrade to Pro or above. |
| 404 | `<resource>_not_found` | The specific row doesn't exist. |
| 429 | `rate_limited` | Per-key rate limit exceeded. Back off + retry; see `Retry-After`. |
| 500 | `server_error` | Internal error. Include `request_id` when you reach out.

## Help

Find issues or need an endpoint we haven't shipped? Open a ticket at **`https://support.mobieus.io/help/portal`** and reference the `request_id` from your last response.