# mobieusCore API — Overview

The mobieusCore REST API gives your tenant programmatic access for reading events, managing users and posts, the full helpdesk surface (tickets, queues, agents, AI hooks), mobieusLearn courses and enrollments, mobieusKnow wiki pages, marketplace listings, moderation, and webhooks.

## Plan availability

The public REST API is available on **Pro**, **Creator Plus**, and **Sovereign** plans. Starter tenants get `403 plan_gated` on every call.

## What's in the API

- **REST + JSON.** GETs read, POSTs change.
- **Bearer auth.** `Authorization: Bearer mc_live_...`. Mint keys at `/admin/api-keys`.
- **Per-tenant.** Every endpoint lives on your subdomain. A key from tenant A cannot read tenant B.
- **CORS enabled.** Every `/api/v1/*` endpoint emits CORS headers and handles `OPTIONS` preflight. Call the API from a browser directly.
- **Idempotency-Key.** POST requests accept `Idempotency-Key` for safe retry (24h TTL, scoped to key + tenant + path).
- **Cursor-paginated lists.** Pass `?cursor=...&limit=N` (max 100). Each list response includes `total_count`, `has_more`, and `next_cursor`.

## 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`, `webhooks:read`, `webhooks:manage` | this page |
| **mobieusHelp** | tickets, queues, agents, canned responses, tags, AI hooks | `helpdesk:read`, `helpdesk:write`, `helpdesk:admin` | [api-helpdesk](/know/api-helpdesk) |
| **mobieusLearn** | courses, modules, lessons, enrollments, certificates, SCORM, xAPI, cohort grants | `learn:read`, `learn:write`, `learn:xapi:read`, `learn:xapi:write`, `learn:cohorts:grant` | [api-learn](/know/api-learn) |
| **mobieusKnow** | wiki pages, revisions, search | `know:read`, `know:write` | [api-knowledge](/know/api-knowledge) |
| **SCIM 2.0** | users, groups (RFC 7644 provisioning) | Bearer token minted at `/admin/learn/scim-credentials` | [api-scim](/know/api-scim) |

> Reading moderation actions (`GET /api/v1/moderation/actions`) uses the `reports:read` scope. There is no separate moderation scope.

> SCIM 2.0 is part of mobieusLearn and needs the mobieusLearn SCIM feature enabled. It is not configured from `/admin/config` — see [api-scim](/know/api-scim).

## Current version: 1.6.0

| Version | Date | What changed |
|---|---|---|
| **1.6.0** | 2026-06-07 | CORS on all API routes. Idempotency-Key on POST. `total_count` + `has_more` on all list responses. 9 new webhook events (helpdesk, Learn, Know). SCIM 2.0 in spec. |
| 1.5.0 | 2026-06-05 | xAPI LRS endpoints + cohort-grant endpoint (`POST /api/v1/learn/cohorts/grant`). |
| 1.4.0 | 2026-06-03 | mobieusLearn live sessions (schedule, cancel, attach recording). |
| 1.3.0 | 2026-06-02 | mobieusLearn (25 endpoints), mobieusKnow (10 endpoints), mobieusHelp Phase 2 + 8 AI hooks. |
| 1.2.0 | 2026-05-29 | mobieusHelp tickets / queues / agents / reply / status. |
| 1.1.0 | 2026-05-28 | Webhooks (HMAC-signed + retry + rotation). 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`. 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_...'
```

## Idempotency example

```bash
POST /api/v1/helpdesk/tickets
Authorization: Bearer mc_live_...
Idempotency-Key: create-ticket-abc123
Content-Type: application/json

{"subject": "Help needed", "body": "..."}
```

Retry with the same `Idempotency-Key` within 24 hours — the original response is replayed with `Idempotency-Replayed: true` and no duplicate ticket is created.

## CORS

All `/api/v1/*` responses include:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-CSRF-TOKEN, X-Requested-With
```

To restrict allowed origins, set `cors.allowed_origins[]` in your tenant's app.ini. When an allow-list is set, the matching origin is echoed back with `Vary: Origin`.

## Pagination shape (1.6.0)

Every list response now includes three pagination fields:

```json
{
  "data": [...],
  "next_cursor": "cur_abc...",
  "total_count": 847,
  "has_more": true,
  "request_id": "req_..."
}
```