REST API

Forum Pro adds its routes to the Grav API plugin, under /api/v1/forum-pro/. The Forum area in Admin Next is built on these routes, and members can read, post, reply, edit, react and report through them too, so a script or a bot can do what a member does on the forum. Paths below leave out the /api/v1 prefix.

Authenticate

Use any credential the API plugin accepts:

• An API key, sent as X-API-Key. Create one in Admin Next (your account, then API Keys) or on the server with bin/plugin api keys:generate --user=<username>.
• A JWT from POST /auth/token, sent as X-API-Token (Admin Next does this).

curl -k "https://example.test/api/v1/forum-pro/structure" -H "X-API-Key: $KEY"

Who may call what

There are two kinds of route, and they are authorized differently.

Content routes (reading and writing topics and posts) act as the forum member linked to the calling account. They need no Grav permission, not even api.access. The forum decides, with exactly the rules it applies on the site: the category permissions for reading, starting topics and replying, closed topics and categories, the edit window, bans, rate limits, spam scoring, premoderation, and the provisional account restrictions. A post made through the API is the same as one made on the forum, and notifies, counts and appears live the same way.

The member is the account's linked forum account, created on its first call the way it is on a first visit (Grav accounts). A content write is refused when:

• auth.grav_members is false, so Grav accounts are not forum members (403 You must be logged in to …).
• The forum account is suspended or deleted.
• The account has not chosen a forum username yet.
• The category does not let that member's groups do it.
• The forum is in read-only mode (503). Staff keep writing unless maintenance.include_staff is on, as on the forum.

An account holding admin.forum-pro.moderate, admin.forum-pro.admin or api.super, or a moderator role, is staff on these routes, and may edit and delete other people's posts and change topics, within its moderation scope.

Management routes (structure, the queue, bans, moderators, groups, tags, members, invites, status and metrics) need api.access plus a Forum Pro permission (Permissions). The tables say admin for admin.forum-pro.admin and moderate for admin.forum-pro.moderate; admin and api.super count as both. Read-only mode does not close them, as it does not close the Forum area in Admin Next.

Keys with scopes

A key created without scopes, a JWT and a session have the account's full access: a member's key posts as that member, and a moderator's key moderates. A key created with scopes is limited to them:

A scope never adds a power the account lacks. A moderator's key that should change topics needs both api.forum-pro.post and admin.forum-pro.moderate; with only api.forum-pro.post it posts as an ordinary member. Scopes are set when the key is created, with POST /users/{username}/api-keys and {"name": "Forum bot", "scopes": ["api.forum-pro.post"]}.

For a bot or an integration, create a dedicated Grav account, sign in to the forum with it once to choose a username, and create a key on that account scoped to api.forum-pro.post. Its posts then carry its own name, and it can do nothing else.

Public reads

The four read routes, GET /forum-pro/structure, GET /forum-pro/categories/{id}/topics, GET /forum-pro/topics/{id} and GET /forum-pro/topics/{id}/posts, answer without credentials. A guest gets what a guest may read on the forum; send a key and the answer includes what that member may read. A topic the caller cannot see answers 404, the same as one that does not exist. With gate.private on, the forum has no public API and these routes need credentials too.

Conventions

• Answers wrap their payload in data. Lists take page and per_page and carry meta.pagination (page, per_page, total, total_pages) and links.
• Errors are problem details (application/problem+json) with status, title and detail. The forum's reason is in detail: 422 Title must be between 3 and 255 characters, 403 You are not allowed to reply in this category, 409 This topic is closed.
• Times are UTC epoch seconds.
• Post bodies are sent as Markdown in body_md and rendered on the server, @mentions and quotes included. Reads answer the rendered body_html.
• Writes send an X-Invalidates header (forum:topic:<id>, forum:category:<id>, forum:structure, …) so Admin Next refetches what changed. GET /forum-pro/topics/{id} sends an ETag.

Routes

Reading

Topics and posts

A topic or reply can be born pending rather than published, when the category premoderates the member or the spam score holds it for review. It then appears once a moderator approves it.

Moderation

Structure

Moderators, groups and tags

Members and invitations

Status and metrics

A quick check with curl

KEY=...   # an API key on the account the bot posts as
BASE=https://example.test/api/v1/forum-pro

# Find a category id
curl -k "$BASE/structure" -H "X-API-Key: $KEY"

# Start a topic in it
curl -k -X POST "$BASE/topics" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"category_id": 3, "title": "Nightly build 2.0.4 is out", "body_md": "Changes since yesterday: ..."}'

# Reply to topic 9434
curl -k -X POST "$BASE/topics/9434/posts" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body_md": "Thanks, that fixed it for me."}'

Related

• Administration
• Members and Accounts
• Moderation
• Grav API: Authentication