# mobieusCore API — Overview

The mobieusCore REST API gives your tenant programmatic access for reading and writing forum posts, marketplace listings, files, a community calendar, the social graph, and automation rules, the full mobieusHelp surface (tickets, queues, agents, and mobieusAI support assists), mobieusLearn courses and enrollments, mobieusKnow pages, marketplace listings, moderation, and webhooks.

## Plan availability

The public REST API is available on **Pro**, **Creator**, **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 (read + reply write), **forums + threads (read, create, reply, lock/pin)**, **profile + avatar**, **image upload**, **block list**, listings (read + write, Q&A, create), files (read + upload), calendar events + RSVPs, follows + post reactions, automation rules, reports, moderation, webhooks | `events:read`, `users:read`, `posts:read`, `posts:write`, `listings:read`, `listings:write`, `files:read`, `files:write`, `calendar:read`, `calendar:write`, `social:read`, `social:write`, `automation:read`, `automation:write`, `reports:read`, `reports:manage`, `webhooks:read`, `webhooks:manage` | this page |
| **mobieusHelp** | tickets, queues, agents, canned responses, tags, help topics, notification prefs, audit, mobieusAI assists | `helpdesk:read`, `helpdesk:write`, `helpdesk:admin` | [api-helpdesk](/know/api-helpdesk) |
| **mobieusLearn** | courses, modules, lessons, activities, enrollments, attempts, certificates, SCORM, xAPI, cohort grants | `learn:read`, `learn:write`, `learn:xapi:read`, `learn:xapi:write`, `learn:cohorts:grant` | [api-learn](/know/api-learn) |
| **mobieusKnow** | 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) |
| **mobieusBuddy** | peer accountability, sharing grants, consented reads of a buddy's health data, nudges/cheers/comments, pacts | `health:read`, `health:write`, `social:read`, `social:write` | [api-buddy-challenge](/know/api-buddy-challenge) |
| **mobieusChallenge** | challenges, join/leave, leaderboards from scored health metrics, feed, invitations, flags | `health:read`, `health:write`, `social:read`, `social:write` | [api-buddy-challenge](/know/api-buddy-challenge) |
| **SCIM 2.0** | user + group provisioning (RFC 7644). Separate credential, outside `/api/v1` | *(no scopes — its own token)* | [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).

## mobieusAI support assists

mobieusHelp exposes mobieusAI helpers as API endpoints. Each runs on your tenant's own Anthropic key and only responds when its feature flag is on at `/admin/ai`.

| Endpoint | Method | What it returns |
|---|---|---|
| `/api/v1/helpdesk/ai/reply-suggest` | POST | A drafted reply for a ticket |
| `/api/v1/helpdesk/ai/summary` | POST | A short summary of a ticket thread |
| `/api/v1/helpdesk/ai/categorize` | POST | A suggested category for a ticket |
| `/api/v1/helpdesk/ai/sentiment` | POST | The sentiment of a ticket |
| `/api/v1/helpdesk/ai/resolution-predict` | POST | A predicted resolution path |
| `/api/v1/helpdesk/ai/audit-qa` | POST | A QA review of an agent reply |
| `/api/v1/helpdesk/ai/canned-generate` | POST | A drafted canned response |
| `/api/v1/helpdesk/ai/knowledge-gaps` | GET | Topics your knowledge base is missing |

See [api-helpdesk](/know/api-helpdesk) for request and response shapes.

## Current version: 1.23.0

Versions 1.8.0–1.18.0 all shipped on 2026-06-19 and were originally recorded here as a single
1.14.0 row. The individual rows below were recovered from the commits that changed the spec's
version, so every date is the real one.


| Version | Date | What changed |
|---|---|---|
| **1.23.0** | 2026-07-28 | Documentation release. The reference now covers the whole reachable surface — mobieusHealth (142 endpoints), mobieusBuddy, mobieusChallenge, forums and threads, profile and social, SCIM 2.0, and the helpdesk bulk action. Adds an `X-API-Version` response header, a second security scheme for the SCIM credential, and machine-readable `x-required-scopes` / `x-plan-required` / `x-feature-flag` on every operation. Scope enforcement was added to 43 routes that previously required none. |
| 1.22.0 | 2026-07-11 | Fasting-coach and expanded branded/restaurant food coverage surfaced through the health endpoints. |
| 1.21.0 | 2026-07-07 | Reference reconciled to the shipped `/api/v1` surface. |
| 1.20.0 | 2026-07-02 | Security-remediation conformance pass over the documented surface. |
| 1.19.0 | 2026-06-26 | **mobieusHealth API** — user-scoped, privacy-preserving health endpoints. |
| 1.18.0 | 2026-06-19 | Automation rules gain `schedule` and `next_run_at`. |
| 1.17.0 | 2026-06-19 | Automation threshold-condition operator. |
| 1.16.0 | 2026-06-19 | `sla.breached` webhook event, plus new automation actions. |
| 1.15.0 | 2026-06-19 | Automation conditions gain regex, groups, and time-windows. |
| **1.14.0** | 2026-06-19 | The API now writes across the core surface. Create forum replies (`posts:write`); edit, sell, withdraw, and create marketplace listings and post Q&A replies (`listings:write`); upload files into a moderation queue (`files:write`); read and manage a community events calendar with RSVPs (`calendar:read`/`calendar:write`); follow members and react to posts (`social:read`/`social:write`); and read and manage automation rules (`automation:read`/`automation:write`). Each new action also emits a webhook event. |
| 1.13.0 | 2026-06-19 | Social graph and reactions. |
| 1.12.0 | 2026-06-19 | `/api/v1/calendar` — read and manage community calendar events. |
| 1.11.0 | 2026-06-19 | `POST /api/v1/listings` plus full-field listing edit. |
| 1.10.0 | 2026-06-19 | `POST /api/v1/files` multipart upload. |
| 1.9.0 | 2026-06-19 | Marketplace write endpoints. |
| 1.8.0 | 2026-06-19 | `POST /posts` create, update, and delete. |
| **1.7.0** | 2026-06-14 | Documentation release. The full reference now covers the mobieusAI support assists, all of mobieusHelp (Phase 2 + write endpoints), mobieusLearn (courses, modules, lessons, activities, enrollments, cohorts, attempts, certificates, SCORM), and mobieusKnow. Corrected paths: helpdesk is `/api/v1/helpdesk`; SCIM is `/scim/v2/*`; ticket-by-reference uses `{ref}`. No endpoint changed its contract. |
| 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 `/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_..."
}
```

## mobieusHealth (1.19.0)

A Pro+ tenant with mobieusHealth can read and log a member's own health data over the REST API:

- `GET /api/v1/health/summary` — today's totals vs goals
- `GET` / `POST /api/v1/health/weight` — list / log weigh-ins
- `GET` / `POST /api/v1/health/vitals` — list / log blood pressure, glucose, resting HR
- `GET` / `POST /api/v1/health/water` — list / add hydration
- `GET /api/v1/health/activity` — list activity sessions

Use the scopes `health:read` and `health:write`. For privacy, these endpoints are **strictly scoped to the API key's owning user** — a key only ever reads and writes that one member's own encrypted record, and no request parameter can address another member's data. The caller must hold an active mobieusHealth seat; without one the API returns `403`. Full request/response details are in the API reference at `/api/docs`.