REST API Reference

Jetonomy exposes a comprehensive REST API under the jetonomy/v1 namespace with 61+ endpoints across 15 controllers. All endpoints are prefixed with /wp-json/jetonomy/v1.

Authentication

Jetonomy supports two authentication methods:

Method	Use Case	Header
WP REST Nonce	Browser-based requests from logged-in users	`X-WP-Nonce: {nonce}`
Application Passwords	External integrations, mobile apps, CI/CD	`Authorization: Basic base64(username:app_password)`

Nonces are generated via wp_create_nonce( 'wp_rest' ) and passed either as the X-WP-Nonce header or as a _wpnonce query parameter. Application Passwords are managed under Users > Application Passwords in wp-admin.

Endpoints marked Auth required return 401 Unauthorized without valid credentials. Endpoints marked Public can be accessed without authentication.

Pagination

Jetonomy supports two pagination strategies:

Offset-based (default)

Parameter	Type	Description
`limit`	int	Number of items to return (default 20, max 100)
`offset`	int	Number of items to skip

Response headers include:

X-JT-Total — total number of items
X-JT-TotalPages — total number of pages

Cursor-based

Parameter	Type	Description
`after`	string	Cursor token from previous response for forward pagination

Use cursor-based pagination for large datasets (10,000+ items) where offset performance degrades.

Rate Limiting

Rate limits are based on the user's trust level:

Trust Level	Requests/Minute
Anonymous	30
New Member	60
Member	120
Regular	180
Leader / Moderator	300
Admin	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit — max requests per window
X-RateLimit-Remaining — remaining requests
X-RateLimit-Reset — seconds until window resets

Error Responses

All errors follow a consistent JSON format:

{
  "code": "jetonomy_not_found",
  "message": "Post not found.",
  "data": {
    "status": 404
  }
}

Common error codes:

HTTP Status	Code	Description
400	`jetonomy_invalid_param`	Missing or invalid parameter
401	`jetonomy_not_logged_in`	Authentication required
403	`jetonomy_forbidden`	Insufficient permissions
404	`jetonomy_not_found`	Resource not found
429	`jetonomy_rate_limited`	Rate limit exceeded

Posts

10 endpoints for creating, reading, updating, and managing posts within spaces.

List Posts in Space

GET /spaces/{space_id}/posts

Returns a paginated list of posts in the specified space.

Parameter	Type	Required	Description
`limit`	int	No	Number of posts to return (default 20)
`offset`	int	No	Number of posts to skip
`sort`	string	No	Sort order: `recent`, `popular`, `unanswered`
`after`	string	No	Cursor for cursor-based pagination

Auth: Public

Create Post

POST /spaces/{space_id}/posts

Creates a new post in the specified space.

Parameter	Type	Required	Description
`title`	string	Yes	Post title
`content`	string	Yes	Post body (HTML)
`tags[]`	array	No	Array of tag slugs or IDs
`status`	string	No	`publish` or `draft` (default `publish`)
`published_at`	string	No	Schedule publication (ISO 8601 datetime)
`captcha_token`	string	Conditional	Required if captcha is enabled in settings

Auth: Required

List User's Drafts

GET /posts/drafts

Returns all draft posts belonging to the authenticated user.

Auth: Required

Get Single Post

GET /posts/{id}

Returns a single post by ID, including vote counts, reply count, tags, and author info.

Auth: Public

Update Post

PATCH /posts/{id}

Updates an existing post. Only the post author or a moderator can update.

Parameter	Type	Required	Description
`title`	string	No	Updated title
`content`	string	No	Updated body
`tags[]`	array	No	Replace tags
`status`	string	No	`publish` or `draft`

Auth: Required (author or moderator)

Delete Post

DELETE /posts/{id}

Deletes a post. Only the post author or a moderator can delete.

Auth: Required (author or moderator)

Close Post

POST /posts/{id}/close

Closes a post in Q&A-type spaces, preventing new replies.

Auth: Required (author or moderator)

Pin/Unpin Post

POST /posts/{id}/pin

Toggles the pinned state of a post. Pinned posts appear at the top of the space.

Auth: Moderator+

Move Post to Space

POST /posts/{id}/move

Moves a post from its current space to a different space.

Parameter	Type	Required	Description
`target_space_id`	int	Yes	Destination space ID

Auth: Moderator+

Merge Posts

POST /posts/{id}/merge

Merges the current post into a target post. Replies from the source post are moved to the target.

Parameter	Type	Required	Description
`target_post_id`	int	Yes	Post ID to merge into

Auth: Moderator+

Link Preview

GET /link-preview?url={url}

Fetches Open Graph metadata (title, description, image) for the given URL. Used by the post composer for rich link embeds.

Parameter	Type	Required	Description
`url`	string	Yes	URL to fetch OG metadata for

Auth: Required

Replies

6 endpoints for managing replies on posts.

List Replies

GET /posts/{post_id}/replies

Returns a paginated list of replies for the specified post.

Parameter	Type	Required	Description
`limit`	int	No	Number of replies to return (default 20)
`offset`	int	No	Number of replies to skip
`sort`	string	No	Sort order (e.g., `oldest`, `newest`, `votes`)

Auth: Public

Create Reply

POST /posts/{post_id}/replies

Creates a new reply on the specified post.

Parameter	Type	Required	Description
`content`	string	Yes	Reply body (HTML)
`parent_id`	int	No	Parent reply ID for nested/threaded replies
`captcha_token`	string	Conditional	Required if captcha is enabled

Auth: Required

Update Reply

PATCH /replies/{id}

Updates the content of an existing reply.

Auth: Required (author or moderator)

Delete Reply

DELETE /replies/{id}

Deletes a reply.

Auth: Required (author or moderator)

Accept Answer

POST /replies/{id}/accept

Marks a reply as the accepted answer in Q&A-type spaces. Only the original post author can accept.

Auth: Required (post author)

Split Reply to New Post

POST /replies/{id}/split

Splits a reply out of its current post and creates a new standalone post from it.

Auth: Moderator+

Spaces

11 endpoints for managing community spaces.

List Spaces

GET /spaces

Returns a paginated list of spaces.

Parameter	Type	Required	Description
`limit`	int	No	Number of spaces to return
`offset`	int	No	Number to skip
`sort`	string	No	Sort order
`visibility`	string	No	Filter by visibility (`public`, `private`, `hidden`)

Auth: Public (private/hidden spaces only visible to members)

Create Space

POST /spaces

Creates a new space.

Parameter	Type	Required	Description
`name`	string	Yes	Space name
`description`	string	No	Space description
`type`	string	No	Space type (e.g., `discussion`, `qa`)
`visibility`	string	No	`public`, `private`, or `hidden`
`join_policy`	string	No	`open`, `approval`, or `invite`
`icon`	string	No	Icon identifier or URL

Auth: Admin

Get Space

GET /spaces/{id}

Returns a single space by ID, including settings, member count, and post count.

Auth: Public (private/hidden require membership)

Update Space

PATCH /spaces/{id}

Updates space properties. Settings are merged via array_merge() — you only need to send the keys you want to change.

Auth: Space admin

Delete Space

DELETE /spaces/{id}

Permanently deletes a space and all its posts.

Auth: Admin

List Space Members

GET /spaces/{id}/members

Returns a paginated list of space members with their roles.

Auth: Public

Join Space

POST /spaces/{id}/members

Adds the authenticated user as a member. Respects the space's join_policy:

open — user is added immediately
approval — a join request is created for space admins to review
invite — returns 403 unless the user has a valid invite token

Auth: Required

Leave / Remove Member

DELETE /spaces/{id}/members/{user_id}

Removes a member from the space. Users can remove themselves (leave). Space admins can remove other members.

Auth: Required

Change Member Role

PATCH /spaces/{id}/members/{user_id}

Changes a member's role within the space (e.g., member, moderator, admin).

Auth: Space admin

Generate Invite

POST /spaces/{id}/invite

Generates a unique invite token/link for the space.

Auth: Space admin

Redeem Invite

GET /invite/{token}

Redeems an invite token and adds the user to the space (or redirects to registration if not logged in).

Auth: Public

Users

5 endpoints for user profiles and lookups.

Get Current User

GET /users/me

Returns the authenticated user's full profile including settings and preferences.

Auth: Required

Update Current User

PATCH /users/me

Updates the current user's profile or settings. Settings use a MERGE pattern — only the keys you send are updated; existing keys are preserved.

Auth: Required

Get User Profile

GET /users/{id}

Returns a user's public profile by ID.

Auth: Public

Lookup by Username

GET /users/by-login/{login}

Returns a user's public profile by their username/login.

Auth: Public

User's Posts

GET /users/{id}/posts

Returns a paginated list of posts authored by the specified user.

Auth: Public

Votes

4 endpoints for voting on posts and replies.

Vote on Post

POST /posts/{id}/vote

Casts a vote on a post.

Parameter	Type	Required	Description
`value`	int	Yes	`1` (upvote) or `-1` (downvote)

Re-casting the same vote value toggles it off (removes the vote).

Auth: Required

Remove Post Vote

DELETE /posts/{id}/vote

Removes the authenticated user's vote from a post.

Auth: Required

Vote on Reply

POST /replies/{id}/vote

Casts a vote on a reply. Same toggle behavior as post votes.

Parameter	Type	Required	Description
`value`	int	Yes	`1` (upvote) or `-1` (downvote)

Auth: Required

Remove Reply Vote

DELETE /replies/{id}/vote

Removes the authenticated user's vote from a reply.

Auth: Required

Notifications

4 endpoints for managing user notifications.

List Notifications

GET /notifications

Returns the authenticated user's notifications (paginated).

Auth: Required

Unread Count

GET /notifications/unread-count

Returns the count of unread notifications.

Auth: Required

Update Notification

PATCH /notifications/{id}

Marks a single notification as read or unread.

Auth: Required

Mark All Read

POST /notifications/mark-all-read

Marks all of the authenticated user's notifications as read.

Auth: Required

Moderation

9 endpoints for content moderation. All require the jetonomy_moderate capability.