Workflows API

Create and manage Molecules (multi-step workflows), their steps, and bonds programmatically.

Molecules

List Molecules

GET /api/v1/molecules

Query Parameters

Parameter	Type	Description
`status`	string	Filter: `open`, `in_progress`, `completed`
`page`	int	Page number
`pageSize`	int	Items per page

Get Molecule

GET /api/v1/molecules/{id}

Returns molecule details including steps, bonds, and wave breakdown.

Create Molecule

POST /api/v1/molecules

{
  "name": "Deploy v2.0",
  "description": "Full deployment workflow for version 2.0"
}

Update Molecule

PATCH /api/v1/molecules/{id}

Delete Molecule

DELETE /api/v1/molecules/{id}

Wisps (Steps)

Wisps are the individual steps within a molecule. Each wisp references an issue.

GET /api/v1/wisps?moleculeId={moleculeId}

POST /api/v1/wisps

{
  "moleculeId": "molecule-id",
  "issueId": "issue-id"
}

DELETE /api/v1/wisps/{id}

Bonds (Connections)

Bonds define dependencies between wisps within a molecule.

GET /api/v1/bonds?moleculeId={moleculeId}

POST /api/v1/bonds

{
  "moleculeId": "molecule-id",
  "fromWispId": "wisp-id-1",
  "toWispId": "wisp-id-2"
}

DELETE /api/v1/bonds/{id}

Molecule Templates

GET /api/v1/molecule-templates

POST /api/v1/molecule-templates

POST /api/v1/molecule-templates/{id}/instantiate

Creates a new molecule from a template, generating fresh issues for each step.

Typical AI Agent Workflow

# 1. Get the molecule detail with wave breakdown
GET /api/v1/molecules/{id}

# 2. Find ready steps (wave 1 first, then wave 2, etc.)
#    Look for wisps whose dependencies are all closed

# 3. Claim a ready step's issue
POST /api/v1/issues/{issueId}/claim

# 4. Do the work...

# 5. Close the issue
POST /api/v1/issues/{issueId}/close

# 6. Repeat — next wave's steps become ready