Public API: Workflow run response is minimal; no GET /workflows/<ID> endpoint

[pneumatic-seidler]

Summary

This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.

Problem

Two related issues limit the developer experience when working with workflows via the Public API:

Issue 1: Minimal response from POST /templates/<ID>/run

When launching a new workflow, the response contains only:

• id (workflow ID)
• name
• status: 0
• current_task: 0
• tasks_count: 0

This is insufficient for common integration scenarios:

• No task details — task IDs, names, and assignees are not included
• No UI link — no URL to open the workflow in the Pneumatic web app
• Misleading values — status=0 and tasks_count=0 do not reflect the actual workflow state (the workflow was just created with multiple tasks)
• Wiki inconsistency — the GitHub Wiki suggests the response should include the full workflow object with task details, but the actual API returns a minimal payload

Issue 2: No GET /workflows/<ID> endpoint

After creating a workflow, there is no documented way to retrieve its full current state:

• GET /workflows/fields queries field values by template_id, but requires knowing field api_names in advance
• GET /v2/tasks/<ID> returns a single task, but requires a task ID (which was not in the run response)
• GET /v3/tasks lists tasks, but has no workflow_id filter

There is no GET /workflows/<ID> endpoint to fetch the complete state of a specific workflow.

Impact

Developers building automations ("create workflow, then monitor progress") cannot retrieve workflow state efficiently. They must poll GET /v3/tasks and filter client-side, which is slow and wasteful.

Proposed Solutions

For Issue 1 — Enrich the run response:

• Include the full list of tasks with their IDs, names, and current performers
• Add a url field linking to the workflow in the Pneumatic UI
• Return accurate status and tasks_count values

For Issue 2 — Add GET /workflows/<ID>:

• Return the complete workflow object: metadata, all tasks with status, all kickoff field values, current task, performers, and dates
• Register in the DRF router alongside existing workflow endpoints
• Support the same authentication as other endpoints

Expected Outcome

After launching a workflow, a developer can immediately access all task details from the response, and can later fetch the full workflow state via GET /workflows/<ID> without needing to poll or cross-reference multiple endpoints.