API Reference¶
Every endpoint lives under a single SMF action, index.php?action=api, and takes the resource path in the path parameter:
With a rewrite rule in place the same resource is addressed as /api/v1/members/5 — see Clean URLs. Every path in the tables below is written relative to v1, so the full address is index.php?action=api;path=v1/<path>.
The API must be enabled
The mod ships switched off. Turn it on at Admin → Configuration → Modification Settings → RESTful API ("Enable the API"). While it is off, every endpoint answers 503 Service Unavailable with the error code service_unavailable.
Request basics¶
Authentication¶
Every request needs an API key; the key selects the member whose permissions apply. It is taken from the first source that is present:
- the
Authorization: Bearer <key>header; - the
X-API-Key: <key>header; - the
api_keyquery parameter.
Keys are managed at Admin → Configuration → Modification Settings → RESTful API: each key is an opaque token bound to a member id. See Custom Authentication for replacing the scheme with your own.
Only fully activated accounts (is_activated = 1) can drive the API. A missing, unknown or deactivated key answers 401 with the code unauthorized.
Version prefix¶
The first path segment is the API contract version. Only v1 is accepted; anything else answers 404 with the code not_found and the message Unsupported API version: <segment>.
Methods¶
GET, POST, PUT, PATCH and DELETE are supported. A known path with an unsupported method answers 405 with the code method_not_allowed.
Clients that cannot send verbs other than GET and POST may override the method with the X-HTTP-Method-Override header or the _method query parameter:
The override is only honoured for POST requests.
Request body¶
The body is parsed as JSON when the Content-Type header contains application/json; otherwise the ordinary form-encoded payload is used. Malformed JSON answers 400 with the code bad_request.
Reserved query parameters¶
SMF reserves board, topic, msg, start and action as query parameters: passing one of them makes the core render a forum page instead of reaching action=api. Parent ids therefore travel in the path (/boards/{board_id}/topics), never in the query string. See Adding a Resource for the details.
Pagination¶
Collections accept two query parameters:
limit— page size,1to100, default25;offset— zero-based offset, default0.
Both are clamped to those bounds; out-of-range values are silently corrected rather than rejected.
Response format¶
A single resource¶
A collection¶
Collections add pagination metadata:
{
"data": [
{ "id": 5, "username": "demo" }
],
"meta": {
"total": 42,
"limit": 25,
"offset": 0,
"count": 1
}
}
total is the number of matching rows, count the number of rows in this page.
An error¶
details is added when the error carries extra information (for example the registration errors of POST /members).
Status codes¶
| Code | Meaning |
|---|---|
200 |
The request succeeded; the body carries data |
201 |
The resource was created |
204 |
The request succeeded and has no body (DELETE operations) |
400 |
The request was malformed or a field was invalid (bad_request) |
401 |
The key is missing, unknown or belongs to a deactivated account (unauthorized) |
403 |
The member lacks the permission for the operation (forbidden) |
404 |
The resource or the endpoint does not exist (not_found) |
405 |
The path exists, but not for this method (method_not_allowed) |
429 |
Rate limited by a third-party hook (too_many_requests) |
500 |
An unexpected error occurred; it is logged (internal_error) |
503 |
The API is switched off (service_unavailable) |
Headers¶
Every response is sent as Content-Type: application/json; charset=utf-8 with X-Content-Type-Options: nosniff. Additional headers can be added through the integrate_api_pre_send hook.
Categories¶
Required fields
In the field lists below a field marked required is required for a full replace (PUT). A creation (POST) only demands the fields its endpoint checks explicitly — usually the name and, for boards, the parent category.
| Field | Type | Notes |
|---|---|---|
id |
int | Category id |
name |
string | Category name |
description |
string | Description |
order |
int | Position among the categories (0-based) |
can_collapse |
bool | Whether the category can be collapsed |
| Method | Path | Permission / notes |
|---|---|---|
GET |
categories |
Lists the categories — all of them for members who manage boards (empty included), otherwise only those holding at least one board the member may see |
GET |
categories/{id} |
One category; the payload also carries its visible boards in boards |
GET |
categories/{cat_id}/boards |
The boards of one category |
POST |
categories |
manage_boards; name is required; answers 201 |
PUT |
categories/{id} |
manage_boards; name and description are required |
PATCH |
categories/{id} |
manage_boards; only the supplied fields change |
DELETE |
categories/{id} |
manage_boards; the boards move to ?move_boards_to=<id> or are deleted with the category |
Writable fields: name (required), description (required), order, can_collapse. The SMF column name cat_order is accepted instead of order.
Boards¶
| Field | Type | Notes |
|---|---|---|
id |
int | Board id |
category |
int | Id of the owning category |
parent |
int | Id of the parent board, 0 for a root board |
name |
string | Board name |
description |
string | Description |
num_topics |
int | Number of topics |
num_posts |
int | Number of posts |
order |
int | Position among the sibling boards (0-based) |
| Method | Path | Permission / notes |
|---|---|---|
GET |
boards |
Lists the boards the member may see |
GET |
boards/{id} |
One board |
GET |
boards/{board_id}/topics |
The topics of one board |
POST |
boards |
manage_boards; name and category are required; answers 201 |
PUT |
boards/{id} |
manage_boards; name and description are required |
PATCH |
boards/{id} |
manage_boards; only the supplied fields change |
DELETE |
boards/{id} |
manage_boards; the child boards move to ?move_children_to=<id> or are deleted with the board |
Writable fields: name (required), description (required), category, parent, order, id_profile, id_theme, override_theme, count_posts, member_groups, deny_member_groups, redirect. The SMF column names id_cat, id_parent and board_order are accepted as aliases. A parent board has to live in the same category as the board itself.
Members¶
| Field | Type | Notes |
|---|---|---|
id |
int | Member id |
username |
string | Login name |
name |
string | Real name |
posts |
int | Number of posts |
date_registered |
int | Unix timestamp |
last_login |
int | Unix timestamp |
primary_group |
int | Primary group id |
post_group |
int | Post group id |
additional_groups |
string | Comma-separated group ids |
email |
string | Only for administrators |
personal_text, signature, birthdate, website_title, website_url, usertitle, avatar, show_online, time_format, timezone, time_offset, id_theme, lngfile, smiley_set, pm_receive_from, warning, ignore_boards, secret_question, is_activated |
— | Only for administrators, and only in the single-resource answer |
| Method | Path | Permission / notes |
|---|---|---|
GET |
members |
view_mlist; lists activated members |
GET |
members/{id} |
One member; the private fields are added for administrators |
POST |
members |
moderate_forum; username and email are required; answers 201 |
PUT |
members/{id} |
profile_identity_own for yourself, profile_identity_any for others; username, name and email are required |
PATCH |
members/{id} |
Same permission; only the supplied fields change |
DELETE |
members/{id} |
profile_remove_own for yourself, profile_remove_any for others; an administrator can only be deleted by an administrator |
Writable fields: username (required), name (required), email (required), password, primary_group, post_group, additional_groups, posts, personal_text, signature, birthdate, website_title, website_url, usertitle, avatar, show_online, time_format, timezone, time_offset, id_theme, lngfile, smiley_set, pm_receive_from, warning, ignore_boards, is_activated, secret_question, secret_answer. The SMF column names member_name, real_name, email_address, passwd, id_group and id_post_group are accepted as aliases.
Changing the groups needs manage_membergroups; changing posts, warning, is_activated, secret_question or secret_answer needs moderate_forum. Changing the password of another member needs moderate_forum.
Member groups¶
| Field | Type | Notes |
|---|---|---|
id |
int | Group id |
name |
string | Group name |
description |
string | Description |
type |
int | 0 private, 1 protected, 2 requestable, 3 free |
min_posts |
int | Post threshold; -1 means "not post-based" |
max_messages |
int | Message limit |
color |
string | Colour of the group in the online users list |
icons |
string | Group icons |
hidden |
int | 1 when the group is hidden |
parent |
int | Parent group id |
tfa_required |
bool | Whether the group requires two-factor authentication |
| Method | Path | Permission / notes |
|---|---|---|
GET |
groups |
Hidden groups are listed only for manage_membergroups holders, the moderator group only for administrators |
GET |
groups/{id} |
One group, with the same visibility rules |
POST |
groups |
manage_membergroups; name is required; answers 201 |
PUT |
groups/{id} |
manage_membergroups; name, description, type, min_posts and max_messages are required |
PATCH |
groups/{id} |
manage_membergroups; only the supplied fields change |
DELETE |
groups/{id} |
manage_membergroups; a group used by a paid subscription cannot be deleted |
Writable fields: name (required), description (required), type (required), min_posts (required), max_messages (required), color, icons, hidden, parent, tfa_required. The SMF column names group_name, group_type, online_color and id_parent are accepted as aliases. Protected groups (type = 1) can only be created, changed or deleted by administrators.
Topics¶
| Field | Type | Notes |
|---|---|---|
id |
int | Topic id |
board |
int | Id of the owning board |
subject |
string | Subject of the opening post |
starter |
object | id and name of the topic author |
poster_time |
int | Unix timestamp of the opening post |
num_replies |
int | Number of replies |
num_views |
int | Number of views |
locked |
bool | Whether the topic is locked |
is_sticky |
bool | Whether the topic is pinned |
approved |
bool | Whether the topic is approved |
id_first_msg, id_last_msg |
int | Ids of the first and last message |
body, body_raw |
string | Only in the single-resource answer: parsed and raw text |
| Method | Path | Permission / notes |
|---|---|---|
GET |
topics |
Lists the topics of every visible board; non-administrators see approved topics only |
GET |
topics/{id} |
One topic, with its body |
GET |
boards/{board_id}/topics |
The topics of one board |
POST |
topics |
post_new on the target board; board, subject and body are required; answers 201 |
PUT |
topics/{id} |
modify_own / modify_any; subject is required |
PATCH |
topics/{id} |
Same permission; only the supplied fields change |
DELETE |
topics/{id} |
remove_own / remove_any; the recycle bin is honoured |
Writable fields: subject (required), body, locked, is_sticky, approved, num_views, board. The SMF column names sticky and id_board are accepted as aliases. Locking needs lock_own / lock_any, pinning make_sticky, approving approve_posts and changing the view counter moderate_board.
Posts¶
| Field | Type | Notes |
|---|---|---|
id |
int | Message id |
topic |
int | Id of the owning topic |
board |
int | Id of the owning board |
subject |
string | Subject |
author |
object | id, name and email of the author |
poster_time |
int | Unix timestamp |
modified_time, modified_name, modified_reason |
— | Edit stamp |
icon |
string | Message icon |
smileys_enabled |
bool | Whether smileys are enabled |
approved |
bool | Whether the post is approved |
body, body_raw |
string | Parsed and raw text |
| Method | Path | Permission / notes |
|---|---|---|
GET |
posts/{id} |
One post; non-administrators see approved posts only |
GET |
topics/{topic_id}/posts |
The posts of one topic |
POST |
posts |
post_reply_any / post_reply_own; the body carries topic and body; answers 201 |
PUT |
posts/{id} |
modify_own / modify_any; body is required |
PATCH |
posts/{id} |
Same permission; only the supplied fields change |
DELETE |
posts/{id} |
delete_own / delete_any; the opening post of a topic that still has replies cannot be deleted |
Writable fields: body (required), subject, icon, smileys_enabled, approved, poster_name, poster_email, poster_time, modified_reason. The SMF column name reason is accepted as an alias for modified_reason. Changing poster_name, poster_email or poster_time needs moderate_forum; approving a post needs approve_posts.
Replies name their topic in the body
POST /posts is the only endpoint that takes its parent in the request body instead of the path: the topic id is sent as the topic field. A path such as /topics/{topic_id}/posts would collide with the reserved topic query parameter of SMF.
Third-party routes¶
Routes registered by other mods are addressed exactly like the built-in ones — the version prefix stays part of the URL, the route pattern does not:
See Adding a Resource for the registration example.