Skip to content

api.md

Latest commit

 

History

History
144 lines (107 loc) · 2.4 KB

api.md

File metadata and controls

144 lines (107 loc) · 2.4 KB
Raw

API

Base URL defaults to http://127.0.0.1:8787.

If PUTER_API_TOKEN is set, all /v1/* endpoints require:

Authorization: Bearer <token>

Health

GET /healthz
GET /readyz

Intake

POST /v1/intake
{
  "title": "Fix onboarding bug",
  "body": "Context and acceptance criteria",
  "source": "cli",
  "actor": "lakshya",
  "project": "puter",
  "repo": "luckybucky9/puter",
  "areas": ["apps/api"],
  "links": ["https://example.com/context"],
  "ready": false,
  "idempotencyKey": "source-event-id"
}

ready: true creates the issue in the configured ready state. Otherwise the issue is created in Backlog.

Claim

POST /v1/issues/PUT-123/claim
{
  "project": "puter",
  "surface": "codex",
  "owner": "agent-name",
  "branch": "agent/PUT-123-short-title",
  "workspace": "host:/path",
  "areas": ["apps/api"],
  "ttlMinutes": 120
}

Returns 409 Conflict if another active workpad overlaps the same areas.

Discover

POST /v1/issues/PUT-123/discover

Creates a linked follow-up issue in Backlog.

Conflict

POST /v1/issues/PUT-123/conflict

Creates an explicit integration issue.

Handoff

POST /v1/issues/PUT-123/handoff
{
  "pr": "https://github.com/luckybucky9/puter/pull/12",
  "validation": "pnpm test passed",
  "notes": "No known limitations"
}

Updates the workpad and moves the issue to the configured review state.

Report

POST /v1/issues/PUT-123/report
{
  "status": "failed",
  "exitCode": 1,
  "command": "pnpm test",
  "validation": "Command exited 1: pnpm test",
  "notes": "CI failed before handoff."
}

Appends a ### Report block to the Puter Workpad without moving the Linear issue. Use this for worker startup, failure, or blocked-state notes that should stay visible while the issue remains claimed.

Close

POST /v1/issues/PUT-123/close
{
  "project": "puter",
  "state": "Done",
  "reason": "Validation passed and artifacts are linked."
}

Moves the issue to a terminal workflow state. If state is omitted, Puter uses the first configured terminal state, which defaults to Done.

Context

GET /v1/issues/PUT-123/context

Returns the Linear issue plus parsed Puter workpad.

Symphony Refresh

POST /v1/projects/puter/refresh

Calls the configured Symphony /api/v1/refresh endpoint if present.