API Reference

List all workflows for the authenticated tenant.

Response

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Market Research Report",
      "description": "Researches a topic and produces a report",
      "created_at": "2026-02-27T10:30:00Z",
      "updated_at": "2026-02-27T10:30:00Z"
    }
  ]
}

Create a new workflow. The markdown is compiled into an execution plan automatically.

Request Body

{
  "markdown": "# My Workflow\n\n## Inputs\n- topic: ...\n\n## Agents\n..."
}

Response

{
  "id": "wf_abc123",
  "name": "My Workflow",
  "markdown": "...",
  "execution_plan": {...},
  "created_at": "2026-02-27T10:30:00Z"
}

Get a workflow by ID, including the compiled execution plan.

Update a workflow's markdown. Re-compiles the execution plan.

Request Body

{
  "markdown": "# Updated Workflow\n..."
}

Delete a workflow by ID.

Compile markdown into an execution plan without saving. Useful for validation and preview.

Request Body

{
  "markdown": "# My Workflow\n..."
}

Response

{
  "valid": true,
  "name": "My Workflow",
  "description": "...",
  "inputs": [...],
  "agents": [...],
  "steps": [...],
  "output": "steps.final.output",
  "output_type": "markdown",
  "compiler_notes": []
}

Start a new execution of a workflow. Returns immediately with the execution ID.

Request Body

{
  "inputs": {
    "topic": "AI in healthcare",
    "depth": "deep"
  }
}

Response

{
  "execution_id": "exec_xyz789",
  "status": "running",
  "started_at": "2026-02-27T10:30:00Z"
}

List all executions for the authenticated tenant, ordered by most recent first.

Get execution status, including final output when complete.

Response

{
  "execution_id": "exec_xyz789",
  "workflow_id": "wf_abc123",
  "workflow_name": "Market Research Report",
  "status": "completed",
  "started_at": "2026-02-27T10:30:00Z",
  "completed_at": "2026-02-27T10:32:15Z",
  "steps_completed": 3,
  "steps_total": 3,
  "final_output": "# Market Research Report\n...",
  "output_type": "markdown",
  "inputs": {"topic": "AI in healthcare"}
}

Get step-level results for an execution.

Response

{
  "steps": [
    {
      "step_id": "research",
      "agent_id": "researcher",
      "status": "completed",
      "model": "sonnet",
      "output": "Based on my research...",
      "tokens": {"input": 1250, "output": 3400},
      "turns": 3,
      "tool_calls": 5
    }
  ]
}

Stop a running execution. Sets status to stopped.

Approve or reject an approval gate step.

Request Body

{
  "approved": true,
  "reason": "Looks good, proceed."
}

Create a persistent public share link for a completed execution's output. The output is uploaded to S3 and served via go.appxen.ai. Idempotent — calling again returns the existing link.

Response

{
  "share_url": "https://go.appxen.ai/abc123-def456"
}

Revoke a share link. Deletes the S3 object so the link returns 404.

Refine the execution output by providing a follow-up prompt. The refinement runs asynchronously — poll the execution to check refine_status. Each refinement creates a new output version.

Request Body

{
  "prompt": "Make the introduction more concise and add a call-to-action at the end."
}

Response

{
  "status": "refining",
  "message": "Refinement started"
}

List all output versions for an execution. Version 1 is the original output; subsequent versions are refinements.

Response

{
  "versions": [
    {
      "version": 2,
      "prompt": "Make the intro more concise",
      "created_at": "2026-03-09T15:30:00Z"
    },
    {
      "version": 1,
      "prompt": null,
      "created_at": "2026-03-09T15:00:00Z"
    }
  ]
}

Get the output for a specific version.

Response

{
  "version": 1,
  "output": "# Original Report\n...",
  "output_type": "markdown",
  "prompt": null,
  "created_at": "2026-03-09T15:00:00Z"
}