REST API Reference

HELIX Mission Control exposes a REST API at /api/. All endpoints return JSON and require JWT authentication unless noted otherwise.

Authentication

http

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin@company.com&password=yourpassword

Response:

json

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "name": "Clement",
    "email": "admin@company.com",
    "role": "admin"
  }
}

Using the Token

Include the JWT token in the Authorization header for all subsequent requests:

http

Authorization: Bearer eyJhbGciOi...

Tokens expire after 24 hours. Request a new token by logging in again.

Get Current User

http

GET /api/auth/me

Update Profile

http

PATCH /api/auth/me
Content-Type: application/json

{
  "name": "New Name",
  "telegram_notifications": true,
  "telegram_user_id": "12345678"
}

Change Password

http

POST /api/auth/me/change-password
Content-Type: application/json

{
  "current_password": "oldpass",
  "new_password": "newpass"
}

Upload Avatar

http

POST /api/auth/me/avatar
Content-Type: multipart/form-data

file: <image file> (JPEG, PNG, or WebP, max 2MB)

Users (Admin Only)

List Users

http

GET /api/users

Create User

http

POST /api/users
Content-Type: application/json

{
  "name": "Jane",
  "email": "jane@company.com",
  "password": "securepass",
  "role": "member"
}

Update User

http

PATCH /api/users/{user_id}
Content-Type: application/json

{
  "name": "Jane Smith",
  "role": "admin"
}

Delete User

http

DELETE /api/users/{user_id}

Departments

List Departments

http

GET /api/departments/

Response:

json

[
  {
    "id": 1,
    "name": "Marketing",
    "emoji": "\ud83d\udce3",
    "sort_order": 1
  }
]

Boards

List Boards

http

GET /api/boards/
GET /api/boards/?department_id=1

Agents

List Agents

http

GET /api/agents/
GET /api/agents/?department_id=1
GET /api/agents/?board_id=3

Create Agent

http

POST /api/agents/
Content-Type: application/json

{
  "name": "Atlas",
  "role_title": "Research Analyst",
  "department_id": 1,
  "primary_board_id": 1,
  "system_prompt": "You are Atlas, a research analyst...",
  "execution_mode": "manual"
}

Get Agent

http

GET /api/agents/{agent_id}

Update Agent

http

PATCH /api/agents/{agent_id}
Content-Type: application/json

{
  "system_prompt": "Updated prompt...",
  "execution_mode": "auto"
}

Delete Agent

http

DELETE /api/agents/{agent_id}

Agent Statistics

http

GET /api/agents/{agent_id}/stats

Agent Tasks (Paginated)

http

GET /api/agents/{agent_id}/tasks?page=1&per_page=10

Tasks

List Tasks

http

GET /api/tasks/
GET /api/tasks/?board_id=3
GET /api/tasks/?status=todo
GET /api/tasks/?assigned_agent_id=5
GET /api/tasks/?archived=false

Search Tasks

http

GET /api/tasks/search?q=blog post

Searches task title, description, and assigned agent name.

Create Task

http

POST /api/tasks/
Content-Type: application/json

{
  "title": "Write a blog post about AI tools",
  "description": "Write a 500-word post covering top 5 AI productivity tools",
  "board_id": 4,
  "assigned_agent_id": 5,
  "priority": "medium",
  "due_date": "2026-03-20T00:00:00Z",
  "tags": ["blog", "seo"],
  "requires_approval": true
}

Get Task

http

GET /api/tasks/{task_id}

Update Task

http

PATCH /api/tasks/{task_id}
Content-Type: application/json

{
  "status": "done",
  "priority": "high"
}

Delete Task

http

DELETE /api/tasks/{task_id}

Execute Task

http

POST /api/tasks/{task_id}/execute

Dispatches the task to the assigned agent via the gateway. The agent processes the task and writes a result.

Comments

List Comments

http

GET /api/tasks/{task_id}/comments/

Add Comment

http

POST /api/tasks/{task_id}/comments/
Content-Type: application/json

{
  "content": "Great work @Sierra! Can you add a pricing section?"
}

Mentions are automatically resolved from @Name patterns in the content.

Skills

List Skills

http

GET /api/skills
GET /api/skills?search=brand
GET /api/skills?category=Marketing
GET /api/skills?tag=writing

Create Skill

http

POST /api/skills
Content-Type: application/json

{
  "name": "Brand Voice Guide",
  "description": "Tone and vocabulary rules",
  "category": "Marketing",
  "tags": ["brand", "writing"],
  "content": "# Brand Voice Guide\n\n## Tone\n...",
  "activation_mode": "always"
}

Get Skill

http

GET /api/skills/{id}

Update Skill

http

PATCH /api/skills/{id}
Content-Type: application/json

{
  "content": "Updated content...",
  "version": "1.1.0"
}

Delete Skill

http

DELETE /api/skills/{id}

Export Skill

http

GET /api/skills/{id}/export

Returns the skill as a downloadable .md file.

Import Skill

http

POST /api/skills/import
Content-Type: multipart/form-data

file: <markdown file>

Skill Attachments

http

# List attachments
GET /api/skills/{id}/attachments

# Upload attachment
POST /api/skills/{id}/attachments
Content-Type: multipart/form-data
file: <file>
description: "Brand guidelines PDF"

# Download attachment
GET /api/skill-attachments/{id}/download

# Delete attachment (via skill update)

Skill Agent Assignments

http

GET /api/skills/{id}/agents

AI Models (Admin Only)

List Models

http

GET /api/models/

Create Model

http

POST /api/models/
Content-Type: application/json

{
  "provider": "openai",
  "model_name": "gpt-4o",
  "display_name": "GPT-4o",
  "api_key": "sk-...",
  "base_url": "https://api.openai.com/v1"
}

Test Model Connection

http

POST /api/models/{model_id}/test

Set Default Model

http

POST /api/models/{model_id}/set-default

Update Model

http

PATCH /api/models/{model_id}

Delete Model

http

DELETE /api/models/{model_id}

Gateway

Gateway Status

http

GET /api/gateway/status

Response:

json

{
  "connected": true,
  "pending_tasks": 0,
  "agent_count": 20
}

Execute Task via Gateway

http

POST /api/gateway/tasks/{task_id}/execute

Activity

List Activity

http

GET /api/activity/
GET /api/activity/?entity_type=task
GET /api/activity/?action=task.created
GET /api/activity/?agent_id=5
GET /api/activity/?user_id=1
GET /api/activity/?date_from=2026-03-01&date_to=2026-03-17
GET /api/activity/?page=1&per_page=20

Notifications

List Notifications

http

GET /api/notifications/?page=1&per_page=20
GET /api/notifications/?read=false

Unread Count

http

GET /api/notifications/unread-count

Response: {"unread_count": 5}

Mark as Read

http

PATCH /api/notifications/{notification_id}/read

Mark All as Read

http

POST /api/notifications/read-all

Dashboard

Dashboard Statistics

http

GET /api/dashboard/stats

Returns agent counts, task counts by status, completion metrics.

Dashboard Activity

http

GET /api/dashboard/activity

Returns the most recent activity entries for the dashboard feed.

Mentions

Search Mentionable Entities

http

GET /api/mentions/search?q=sie

Returns matching users and agents for the @mention autocomplete.

Organization Settings

Get Settings

http

GET /api/org/settings

Update Settings

http

PATCH /api/org/settings
Content-Type: application/json

{
  "timezone": "Asia/Kuala_Lumpur"
}

Error Responses

All errors return a JSON object with a detail field:

json

{
  "detail": "Not found"
}

Common HTTP status codes:

Code	Meaning
400	Bad request — invalid input
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not found
422	Validation error — check the `detail` for specifics
500	Internal server error

REST API Reference ​

Authentication ​

Login ​

Using the Token ​

Get Current User ​

Update Profile ​

Change Password ​

Upload Avatar ​

Users (Admin Only) ​

List Users ​

Create User ​

Update User ​

Delete User ​

Departments ​

List Departments ​

Boards ​

List Boards ​

Agents ​

List Agents ​

Create Agent ​

Get Agent ​

Update Agent ​

Delete Agent ​

Agent Statistics ​

Agent Tasks (Paginated) ​

Tasks ​

List Tasks ​

Search Tasks ​

Create Task ​

Get Task ​

Update Task ​

Delete Task ​

Execute Task ​

Comments ​

List Comments ​

Add Comment ​

Skills ​

List Skills ​

Create Skill ​

Get Skill ​

Update Skill ​

Delete Skill ​

Export Skill ​

Import Skill ​

Skill Attachments ​

Skill Agent Assignments ​

AI Models (Admin Only) ​

List Models ​

Create Model ​

Test Model Connection ​

Set Default Model ​

Update Model ​

Delete Model ​

Gateway ​

Gateway Status ​

Execute Task via Gateway ​

Activity ​

List Activity ​

Notifications ​

List Notifications ​

Unread Count ​

Mark as Read ​

Mark All as Read ​

Dashboard ​

Dashboard Statistics ​

Dashboard Activity ​

Mentions ​

Search Mentionable Entities ​

Organization Settings ​

Get Settings ​

Update Settings ​

Error Responses ​

REST API Reference

Authentication

Login

Using the Token

Get Current User

Update Profile

Change Password

Upload Avatar

Users (Admin Only)

List Users

Create User

Update User

Delete User

Departments

List Departments

Boards

List Boards

Agents

List Agents

Create Agent

Get Agent

Update Agent

Delete Agent

Agent Statistics

Agent Tasks (Paginated)

Tasks

List Tasks

Search Tasks

Create Task

Get Task

Update Task

Delete Task

Execute Task

Comments

List Comments

Add Comment

Skills

List Skills

Create Skill

Get Skill

Update Skill

Delete Skill

Export Skill

Import Skill

Skill Attachments

Skill Agent Assignments

AI Models (Admin Only)

List Models

Create Model

Test Model Connection

Set Default Model

Update Model

Delete Model

Gateway

Gateway Status

Execute Task via Gateway

Activity

List Activity

Notifications

List Notifications

Unread Count

Mark as Read

Mark All as Read

Dashboard

Dashboard Statistics

Dashboard Activity

Mentions

Search Mentionable Entities

Organization Settings

Get Settings

Update Settings

Error Responses