Skip to content

API.md

Latest commit

 

History

History
220 lines (170 loc) · 8.47 KB

API.md

File metadata and controls

220 lines (170 loc) · 8.47 KB

Markus API Reference

Base URL: http://localhost:8056

All requests require authentication via one of:

  • JWT Cookie: markus_token (set automatically on login)
  • Header: Authorization: Bearer <token>

Authentication

Method Path Description
POST /api/auth/login Login, returns JWT Cookie
POST /api/auth/logout Logout
GET /api/auth/me Get current user info
POST /api/auth/change-password Change password

Agent Management

Method Path Description
GET /api/agents List all agents
POST /api/agents Hire a new agent { name, role, description }
GET /api/agents/:id Get agent details
DELETE /api/agents/:id Fire agent
POST /api/agents/:id/start Start agent
POST /api/agents/:id/stop Stop agent
GET /api/agents/:id/profile Get agent full profile (memory, tools, etc.)

Messages & Conversations

Method Path Description
POST /api/agents/:id/message Send message to agent (SSE streaming)
GET /api/sessions List conversation sessions
GET /api/sessions/:id/messages Get session message history
GET /api/channels/:channel/messages Get channel history
POST /api/channels/:channel/messages Send channel message (supports SSE streaming)

Tasks

Method Path Description
GET /api/tasks List tasks (supports ?status=, ?assignedAgentId= filters)
POST /api/tasks Create task
GET /api/taskboard Get Kanban board data
PATCH /api/tasks/:id Update task (status, notes, etc.)
POST /api/tasks/:id/approve Approve a pending task
POST /api/tasks/:id/reject Reject a pending task
POST /api/tasks/:id/cancel Cancel a task (body: { cascade?: boolean })
POST /api/tasks/:id/schedule/pause Pause a scheduled task's recurring schedule
POST /api/tasks/:id/schedule/resume Resume a paused scheduled task
POST /api/tasks/:id/schedule/run-now Trigger an immediate run of a scheduled task
PUT /api/tasks/:id/schedule Update schedule configuration { every?, cron?, maxRuns?, timezone? }
GET /api/tasks/:id/dependent-count Count tasks blocked by this task
POST /api/tasks/:id/comments Post a comment on a task. Body: { content, mentions?, authorId?, authorType?, replyTo? }. replyTo is a comment ID for structural reply linking.
POST /api/requirements/:id/comments Post a comment on a requirement. Body: { content, mentions?, authorId?, authorType?, replyTo? }. replyTo is a comment ID for structural reply linking.

Teams

Method Path Description
GET /api/teams List teams
POST /api/teams Create team
GET /api/teams/:id Get team details
PUT /api/teams/:id Update team
DELETE /api/teams/:id Delete team

Governance & System Control

Method Path Description
GET /api/system/status Global status (paused/emergency mode)
POST /api/system/pause-all Pause all agents
POST /api/system/resume-all Resume all agents
POST /api/system/emergency-stop Emergency stop
GET /api/system/announcements Get system announcements
POST /api/system/announcements Create system announcement
GET /api/governance/policy View governance policy
PUT /api/governance/policy Update governance policy

Projects

Method Path Description
GET /api/projects List projects
POST /api/projects Create project
GET /api/projects/:id Get project
PUT /api/projects/:id Update project
DELETE /api/projects/:id Delete project

Delivery & Review

Method Path Description
POST /api/tasks/:id/accept Accept task delivery
POST /api/tasks/:id/revision Request revision
POST /api/tasks/:id/archive Archive task

Reports & Knowledge

Method Path Description
GET /api/reports List reports
POST /api/reports/generate Trigger report generation
GET /api/reports/:id Report details
POST /api/reports/:id/plan/approve Approve plan
POST /api/reports/:id/plan/reject Reject plan
GET /api/reports/:id/feedback Get report feedback
POST /api/reports/:id/feedback Create report feedback
POST /api/knowledge Contribute knowledge
GET /api/knowledge/search Search knowledge base

Users

Method Path Description
GET /api/users List human users (includes hasJoined flag)
POST /api/users Create human user { name, email, role } — returns invite token
PATCH /api/users/:id Update user (name, role, email)
POST /api/users/:id/reset-password Admin password reset
DELETE /api/users/:id Delete user

Invite Flow

Method Path Description
GET /api/auth/invite/:token Validate invite token — returns user info (name, email)
POST /api/auth/invite/:token/setup Complete registration { password, name?, email? }

Group Chats

Method Path Description
GET /api/group-chats List group chats for current user
POST /api/group-chats Create custom group chat { name, memberIds: [{id, type}] }
GET /api/group-chats/:id Get group chat details (includes members)
PATCH /api/group-chats/:id Update group chat (name, add/remove members)
DELETE /api/group-chats/:id Delete group chat
POST /api/group-chats/:id/members Add member { userId, userType, userName }
DELETE /api/group-chats/:id/members/:userId Remove member

Notifications

Method Path Description
GET /api/notifications List notifications for current user (supports ?unreadOnly=true&limit=N&offset=N&type=T)
GET /api/notifications/count Get unread notification count
POST /api/notifications/:id/read Mark a single notification as read
POST /api/notifications/read-all Mark all notifications as read

Roles

Method Path Description
GET /api/roles List available role templates
GET /api/roles/:name Get role template details

Health

Method Path Description
GET /api/health Health check (returns { status, version, agents })

WebSocket

Connection: ws://localhost:8056

Event Direction Description
agent:update Server → Client Agent status change
agent:mailbox Server → Client New item in agent mailbox
agent:decision Server → Client Agent attention decision
agent:focus Server → Client Agent switches focus
task:update Server → Client Task status update
task:create Server → Client New task created
requirement:created Server → Client New requirement proposed
chat Server → Client Agent message in channel
task:comment Server → Client New task comment (includes replyTo, replyToAuthor, replyToContent for reply-linked comments)
requirement:comment Server → Client New requirement comment (includes replyTo, replyToAuthor, replyToContent)
chat:message Server → Client Channel/DM/group message (targeted to members; includes replyToId, replyToSender, replyToText for reply-linked messages)
chat:proactive_message Server → Client Agent activity log or proactive message
chat:group_created Server → Client Group chat created
chat:group_updated Server → Client Group chat membership changed
chat:group_deleted Server → Client Group chat deleted
notification Server → Client (targeted) User notification (targeted by userId)
system:announcement Server → Client System announcement broadcast
system:pause-all Server → Client Global pause event
system:resume-all Server → Client Global resume event
system:emergency-stop Server → Client Emergency stop event