REST API¶

The pm REST API is served alongside the web UI when running pm serve. All endpoints are under /api/v1/.

Base URL¶

http://localhost:8080/api/v1/

Change the port with pm serve --port <port>.

CORS¶

All responses include permissive CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type

Response Format¶

All responses are JSON. Successful responses return the resource or array directly. Errors return:

{
  "error": "error message describing what went wrong"
}

Endpoints¶

Projects¶

Method	Path	Description
`GET`	`/api/v1/projects`	List all projects
`POST`	`/api/v1/projects`	Create a project
`GET`	`/api/v1/projects/{id}`	Get a project by ID
`PUT`	`/api/v1/projects/{id}`	Update a project
`DELETE`	`/api/v1/projects/{id}`	Delete a project
`POST`	`/api/v1/projects/refresh`	Refresh metadata for all projects

Query parameters for GET /api/v1/projects:

Parameter	Type	Description
`group`	string	Filter by project group

Refresh response shape (POST /api/v1/projects/refresh):

{
  "refreshed": 5,
  "total": 9,
  "failed": 0,
  "results": [
    { "name": "my-api", "changed": true },
    { "name": "docs", "changed": false },
    { "name": "broken-project", "changed": false, "error": "project path missing: /old/path" }
  ]
}

Issues¶

Method	Path	Description
`GET`	`/api/v1/issues`	List all issues
`GET`	`/api/v1/issues/{id}`	Get an issue by ID
`PUT`	`/api/v1/issues/{id}`	Update an issue
`DELETE`	`/api/v1/issues/{id}`	Delete an issue
`GET`	`/api/v1/projects/{id}/issues`	List issues for a project
`POST`	`/api/v1/projects/{id}/issues`	Create an issue under a project

Query parameters for GET /api/v1/issues:

Parameter	Type	Description
`status`	string	Filter by status (`open`, `in_progress`, `done`, `closed`)
`priority`	string	Filter by priority (`low`, `medium`, `high`)
`tag`	string	Filter by tag name

Defaults for POST /api/v1/projects/{id}/issues:

When creating an issue, unspecified fields default to: status: "open", priority: "medium", type: "feature".

Status & Health¶

Method	Path	Description
`GET`	`/api/v1/status`	Status overview for all projects
`GET`	`/api/v1/status/{id}`	Status for a single project
`GET`	`/api/v1/health/{id}`	Health score breakdown for a project

Status response shape:

{
  "project": { "id": "...", "name": "...", "path": "...", ... },
  "branch": "main",
  "isDirty": false,
  "openIssues": 3,
  "inProgressIssues": 1,
  "health": 82,
  "lastActivity": "2025-01-15T10:30:00Z"
}

Health response shape:

{
  "Total": 82,
  "GitCleanliness": 15,
  "ActivityRecency": 22,
  "IssueHealth": 16,
  "ReleaseFreshness": 15,
  "BranchHygiene": 14
}

Sessions¶

Method	Path	Description
`GET`	`/api/v1/sessions`	List agent sessions (enriched with project name)
`GET`	`/api/v1/sessions/{id}`	Get session detail with live git state
`POST`	`/api/v1/agent/launch`	Launch or resume an agent session
`POST`	`/api/v1/agent/close`	Close an agent session

Query parameters for GET /api/v1/sessions:

Parameter	Type	Description
`project_id`	string	Filter by project ID

Session list response includes ProjectName resolved from the project ID.

Session detail response (GET /api/v1/sessions/{id}) includes live worktree state:

{
  "ID": "01J5ABCD...",
  "ProjectID": "...",
  "ProjectName": "my-api",
  "Branch": "feature/add-auth",
  "Status": "idle",
  "CommitCount": 5,
  "LastCommitHash": "abc1234",
  "LastCommitMessage": "feat: add login endpoint",
  "LastActiveAt": "2026-02-13T04:30:00Z",
  "WorktreeExists": true,
  "IsDirty": false,
  "CurrentBranch": "feature/add-auth",
  "AheadCount": 3,
  "BehindCount": 0
}

Close agent request (POST /api/v1/agent/close):

{
  "session_id": "01J5ABCD...",
  "status": "completed"
}

Valid status values: idle (default), completed, abandoned.

Tags¶

Method	Path	Description
`GET`	`/api/v1/tags`	List all tags

Examples¶

List all projects¶

curl http://localhost:8080/api/v1/projects

Create an issue¶

curl -X POST http://localhost:8080/api/v1/projects/01J5ABCD1234EFGH5678IJKL/issues \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add rate limiting",
    "priority": "high",
    "type": "feature"
  }'

Get health score for a project¶

curl http://localhost:8080/api/v1/health/01J5ABCD1234EFGH5678IJKL

Filter issues by status¶

curl "http://localhost:8080/api/v1/issues?status=open&priority=high"