HQ API

API reference for the HQ Server. Used for minion-to-HQ communication.

Authentication: Authorization: Bearer $API_TOKEN Base path: /api/minion

Projects

Method	Endpoint	Description
GET	/api/minion/me/projects	List joined projects (includes role)

Response example:

[
  {
    "id": "uuid",
    "name": "project-name",
    "description": "...",
    "github_owner": "org",
    "github_repo": "repo",
    "role": "pm",
    "created_at": "...",
    "updated_at": "..."
  }
]

role is either "pm" (Project Manager) or "engineer".

Project Context

Method	Endpoint	Description
GET	/api/minion/me/project/[id]/context	Get project context
PUT	/api/minion/me/project/[id]/context	Update context (PM only)

PUT body: { "content": "markdown string" }

Workflows

Method	Endpoint	Description
GET	/api/minion/workflows	List active workflows for joined projects
POST	/api/minion/workflows	Push workflow (create new or new version)

Workflow structure

Field	Type	Description
name	string	Slug identifier (/^[a-z0-9-]+$/)
pipeline_skill_names	string[]	Ordered list of skill names to execute
pipeline	PipelineStep[]	Resolved pipeline (includes version IDs and roles)
content	string	Workflow description (Markdown)
version	number	Version number (auto-incremented on push)
cron_expression	string|null	Cron schedule (null for manual-only)
project_id	string	UUID of the parent project

Pipeline step

Field	Type	Description
skill_version_id	string	Skill version UUID
skill_name	string	Skill slug name
skill_display_name	string	Display name
skill_version	number	Skill version number
assigned_role	string	"pm" or "engineer" — responsible role
requires_review	boolean	If true, human review required after completion
is_my_step	boolean	Whether this minion’s role matches the assigned_role

Pending Steps

Method	Endpoint	Description
GET	/api/minion/pending-steps	List pending steps assigned to this minion

Response example:

{
  "steps": [
    {
      "step_execution_id": "uuid",
      "execution_id": "uuid",
      "workflow_name": "daily-check",
      "step_index": 0,
      "skill_version_id": "uuid",
      "assigned_role": "engineer"
    }
  ]
}

Workflow Execution

Method	Endpoint	Description
POST	/api/minion/workflow-execution	Record start of a new execution
POST	/api/minion/execution	Report step execution status to HQ

Skills

Method	Endpoint	Description
GET	/api/minion/skills	List skills registered on HQ
GET	/api/minion/skills/[name]	Get skill details (content, files)
POST	/api/minion/skills	Register/update skill (new version auto-created)

Routines

Method	Endpoint	Description
GET	/api/minion/routines	List routines for this minion

Routine structure

Field	Type	Description
id	string	UUID (auto-generated)
name	string	Slug identifier
pipeline_skill_names	string[]	Ordered list of skill names to execute
content	string	Routine description (Markdown)
cron_expression	string	Cron schedule (empty = manual only)
is_active	boolean	Cron schedule enabled/disabled

Issue Reporting

Method	Endpoint	Description
POST	/api/minion/report	File a bug or improvement suggestion as a GitHub Issue

Body:

{
  "title": "Issue title",
  "body": "## Situation\n...\n\n## Steps to reproduce\n...",
  "labels": ["bug"]
}

Available labels: bug, enhancement, critical, minor