Skip to main content

API Documentation

RESTful API for the PLE platform. Base URL: /api

Endpoints Authentication Content Proposals Discussions Projects Tasks Comments Votes RSS Feed

Authentication

POST/api/authRegister / Login

Authenticate users. Action determined by action field in body.

ParamTypeDescription
actionstringrequired register or login
emailstringrequired User email
passwordstringrequired User password
display_namestringRequired for registration

Returns: { token, user: { id, email, displayName, role } }

GET/api/auth?action=meCurrent userAuth

Returns the authenticated user's profile. Requires Authorization: Bearer <token> header.

GET/api/auth?action=membersList members

Returns all platform members with contribution stats.

GET/api/auth?action=leaderboardContributor leaderboard

Returns top 20 contributors scored by activity (articles: 10pts, proposals: 5pts, discussions: 3pts, comments: 1pt).

Content

GET/api/contentList content
ParamTypeDescription
statusstringFilter: draft, in_review, approved, published
typestringFilter: article, report, guide, policy_brief
projectIduuidFilter by project
limitintMax results (default: 20, max: 100)
offsetintPagination offset
GET/api/content?id={slug|uuid}Get single content

Returns full content with tags, comments, version count. Accepts slug or UUID. Increments view count for published items.

POST/api/contentCreate contentAuth
ParamTypeDescription
titlestringrequired Content title
bodystringMarkdown body
content_typestringarticle, report, guide, policy_brief
tagsstring[]Array of tag names
project_iduuidLink to project
PUT/api/contentUpdate contentAuth

Update title, body, status, tags, visibility, excerpt. Requires id in body. Authors can edit own content; editors/admins can edit any.

GET/api/content?action=versions&id={uuid}Version history

Returns version history for a content item: version number, title, change summary, editor, timestamp.

Proposals

GET/api/proposalsList proposals
ParamTypeDescription
statusstringdraft, open, accepted, rejected, implemented, withdrawn
authorIduuidFilter by author
limitintMax results (default: 20)
POST/api/proposalsCreate proposalAuth
ParamTypeDescription
titlestringrequired
contentstringrequired Markdown description
proposalTypestringrequired governance, content, project, architecture, community
elementIduuidLink to architecture element
votingEndsdateVoting deadline

Discussions

GET/api/discussionsList discussions
ParamTypeDescription
typestringquestion, idea, feedback, general
authorIduuidFilter by author
POST/api/discussionsCreate discussionAuth

Body: { title, body, discussion_type }

Projects

GET/api/projectsList projects

Returns all projects with task stats, member counts, and milestone info. Supports limit and offset.

POST/api/projectsCreate projectAuth

Body: { title, description, status }

Tasks

GET/api/tasksList tasks
ParamTypeDescription
projectIduuidFilter by project
parent_iduuidGet subtasks of a parent task
statusstringbacklog, todo, in_progress, review, done, blocked
assignedTouuid|me|unassignedFilter by assignee
milestoneIduuidFilter by milestone
POST/api/tasksCreate taskAuth

Body: { project_id, title, description, status, priority, assigned_to, parent_task_id, due_date, estimated_hours }

Comments

GET/api/commentsList comments

Query: entity_type (content, task, proposal, discussion, project) + entity_id

POST/api/commentsPost commentAuth

Body: { entity_type, entity_id, body, parent_id }. Supports threaded replies via parent_id.

Votes

POST/api/votesCast voteAuth

Body: { proposal_id, vote_type } where vote_type is approve, reject, or abstain. One vote per user per proposal.

RSS Feed

GET/api/rssRSS 2.0 Feed

Returns RSS 2.0 XML of the 20 most recent published content items. Content-Type: application/rss+xml. Cached for 1 hour.

Authentication

Endpoints marked with Auth require a Bearer token. Obtain one via POST /api/auth with action: "login", then include Authorization: Bearer <token> in subsequent requests.