HTTP API

The frontend talks to the backend over a JSON API under /api. There is no separate API documentation site yet; this page lists the main groups and the conventions.

caution

The API is the one the bundled frontend uses. It is not yet a versioned, stable public API: endpoints and parameters can change between minor releases. Tell us on the forum or in a GitHub issue if you need a stable integration.

Conventions

• Requests and responses are JSON. An upload uses multipart/form-data.
• A response has the shape {"status": "ok", "msg": "", "data": ...}. Errors use "status": "error" and a message in msg; check status, not only the HTTP code.
• Authentication is a session cookie named casnode_session_id. Call /api/signin, /api/login or the auth flow first and send the cookie with later requests.
• Reads are open where the forum is public; writes require a signed-in member, and admin endpoints require an administrator. A forum with login_required on refuses reads to anonymous visitors too.

Main endpoints

Site and accounts

Method	Path	Purpose
GET	/api/get-site	Public site settings, categories and the current user.
POST	/api/signup	Create a local account.
POST	/api/login	Log in with a user name or email and a password.
POST	/api/signin	Log in through Casdoor (the old /api/signin flow).
POST	/api/signout	End the session.
POST	/api/forgot-password, /api/reset-password, /api/change-password	Password reset and change.
GET	/api/auth/start	Start a single sign-on flow (provider parameter).
GET	/api/auth/callback/:provider	The callback registered at the provider.
GET	/api/get-account	The signed-in account.

Topics and posts

Method	Path	Purpose
GET	/api/get-topics	Topic lists (latest, new, unread, hot, top, category, tag).
GET	/api/get-topic	One topic with its posts.
GET	/api/get-posts	Posts of a topic, in pages.
POST	/api/add-topic, /api/update-topic, /api/set-topic-status, /api/delete-topic, /api/recover-topic	Create, edit, close/pin/archive, delete and recover.
POST	/api/add-post, /api/update-post, /api/delete-post, /api/recover-post	Replies and edits.
POST	/api/like-post, /api/bookmark-post, /api/flag-post	Reactions.
POST	/api/preview	Render Markdown for the composer preview.

People, groups and content

Method	Path	Purpose
GET	/api/get-user, /api/get-user-activity, /api/get-directory, /api/search-users	Profiles and the member directory.
GET	/api/get-notifications, POST /api/read-notification	Notifications.
GET	/api/search	Search topics and posts.
GET	/api/get-categories, /api/get-tags	Categories and tags.
GET	/api/get-groups, /api/get-group, /api/get-group-members, /api/get-group-messages	Groups.
GET	/api/get-badges, /api/get-user-badges	Badges.
GET	/api/get-chat-channels, /api/get-chat-messages	Chat.
GET	/api/message-bus-poll	Long poll for live updates (up to 25 seconds).
POST	/api/upload	Upload a file (multipart/form-data).

Administration

Method	Path	Purpose
GET, POST	/api/get-site-settings, /api/update-site-setting	Site settings.
GET, POST	/api/get-admin-users, /api/update-admin-user	Members, admins, suspensions.
GET	/api/get-dashboard	Admin dashboard numbers.
GET, POST	/api/get-auth-providers, /api/save-auth-provider, /api/delete-auth-provider	Single sign-on providers.
POST	/api/send-test-email	The test button on /admin/email.
GET, POST	/api/get-reviewables, /api/perform-reviewable	The review queue.
POST	/api/move-posts	Move or merge posts.

Other paths

• /uploads/<path> serves uploaded files.
• /sitemap.xml, /sitemap_<n>.xml, /robots.txt are generated by the backend.
• /latest.rss, /top.rss, /t/<slug>/<id>.rss and category/tag feeds are RSS.

Read Architecture for how requests reach the frontend, and Development for the code layout.