# mobieusCore API — mobieusKnow

The Know surface of the public REST API. Manage wiki pages, list +
get + approve revisions, run search.

Added in API version **1.3.0** (2026-06-02).

## Scopes

| Scope | Grants |
|---|---|
| `know:read` | List pages, get page + revision, run search. |
| `know:write` | Create / update / delete pages, approve / reject revisions. |

## Quick start

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

```bash
curl -X POST https://YOUR-TENANT.mobieus.io/api/v1/know/pages \
  -H 'Authorization: Bearer mc_live_...' -H 'Content-Type: application/json' \
  -d '{"slug":"refund-policy","title":"Refund policy","content_markdown":"# Refunds\n\n14 days, full refund."}'
```

The body is raw markdown — your tenant renders it on the web at
`/know/refund-policy`. API consumers see the raw markdown back.

## Resources

### Pages

| Method | Path | Scope | What |
|---|---|---|---|
| `GET`  | `/api/v1/know/pages?q=&tag=&author_id=` | `know:read`  | List published pages. `q` matches title or slug; `tag` filters by tag slug. |
| `GET`  | `/api/v1/know/pages/{slug}`             | `know:read`  | Get a page with its current revision's body markdown. |
| `POST` | `/api/v1/know/pages`                    | `know:write` | Create. Body: `{"slug", "title", "content_markdown", "tags": []}`. |
| `POST` | `/api/v1/know/pages/{slug}`             | `know:write` | Update. Updating `content_markdown` creates an approved revision; updating `title` modifies the page row. |
| `POST` | `/api/v1/know/pages/{slug}/delete`      | `know:write` | Soft-delete (status flips to `deleted`). |

### Revisions

| `GET`  | `/api/v1/know/pages/{slug}/revisions` | `know:read`  | List the page's revisions newest-first (max 100). |
| `GET`  | `/api/v1/know/revisions/{id}`         | `know:read`  | Get one revision with its body markdown. |
| `POST` | `/api/v1/know/revisions/{id}/approve` | `know:write` | Approve a pending revision (sets it as the page's current). |
| `POST` | `/api/v1/know/revisions/{id}/reject`  | `know:write` | Reject. Body: `{"reason": "..."}`. Required. |

### Search

| `GET` | `/api/v1/know/search?q=...&limit=N` | `know:read` | LIKE-based search across title + slug + tags on published pages. Returns up to 50 (default 20). |

## Editor flow vs. API flow

In the web UI, an edit from a non-trusted contributor lands as a
`pending` revision that a moderator approves at `/admin/know/queue`.
The API takes a different path: bearer-authenticated writes are
treated as moderator-level, so `POST /api/v1/know/pages/{slug}`
creates an immediately-approved revision and flips the page's
`current_revision_id`. There's no API equivalent of "submit a
pending revision for review" — if you need that workflow, use the
admin UI.

`POST .../revisions/{id}/approve` and `.../reject` are still useful
for managing pending revisions created via the web editor by
non-trusted contributors.

## Response shape

Page rows (`GET /pages` and `GET /pages/{slug}`):

```json
{
  "id": 42,
  "slug": "refund-policy",
  "title": "Refund policy",
  "author_id": 7,
  "status": "published",
  "current_revision_id": 184,
  "view_count": 1241,
  "created_at": "2026-05-10 12:34:56",
  "updated_at": "2026-06-01 09:11:22",
  "content_markdown": "# Refunds\n\n14 days, full refund."
}
```

(`content_markdown` is only included on the single-page endpoint, not
the list.)

## Errors

| Code | When |
|---|---|
| `404 page_not_found` | Slug not found. |
| `404 revision_not_found` | Revision id not found. |
| `400 slug_taken` | Create attempted with a slug already in use. |
| `400 missing_field` | Required body field absent (slug, title, content_markdown, reason). |
| `403 insufficient_scope` | Key doesn't have `know:read` / `know:write`. |