#225 OpenAPI: Workflow Endpoints Documentation (18 endpoints)

## Scope Document all workflow-related API endpoints in `api/blueprints/v1/workflows.py` ## Endpoints to Document (18 total) ### Workflow Submission & Management 1. POST /workflows - Submit new workflow 2. GET /workflows - List workflows (paginated) 3. GET /workflows/{id} - Get workflow details 4. POST /workflows/{id}/cancel - Cancel workflow 5. POST /workflows/{id}/retry - Retry failed workflow ### Workflow Definition 6. GET /workflows/by-hash/{hash} - Get definition by hash 7. GET /workflows/definitions/{id} - Get definition by ID 8. GET /workflows/definitions/json/{id} - Get JSON definition only 9. GET /workflows/definitions/dsl/python/{id} - Get Python DSL 10. GET /workflows/{name}/versions/{version} - Get by name+version ### Workflow Events & State 11. GET /workflows/{id}/events - Get audit log events 12. GET /workflows/{id}/checkpoints - Get checkpoints 13. GET /workflows/{id}/locks - Get lock history 14. GET /workflows/{id}/sagas - Get saga history 15. GET /workflows/{id}/steps/{step}/checkpoints - Get step checkpoints ### Visualization 16. GET /workflows/{id}/graph - Get Mermaid graph 17. GET /workflows/{id}/graph/dot - Get DOT graph ### Analytics 18. GET /workflows/definitions/{id}/executions/grid - Execution grid ## Pydantic Models to Create ```python # api/openapi/models/workflows.py class WorkflowSubmitRequest(BaseModel): workflow_definition: dict | None = None python_dsl: str | None = None inputs: dict = {} queue: str = 'highway_default' created_by: str | None = None affinity_tags: list[str] | None = None class WorkflowSubmitResponse(BaseModel): workflow_run_id: str run_id: str definition_id: str workflow_name: str version: int definition_hash: str is_new_version: bool class WorkflowStatus(str, Enum): PENDING = 'pending' RUNNING = 'running' SLEEPING = 'sleeping' COMPLETED = 'completed' FAILED = 'failed' class WorkflowListItem(BaseModel): workflow_run_id: str workflow_name: str workflow_version: int status: WorkflowStatus created_at: datetime | None # ... more fields class WorkflowDetail(WorkflowListItem): inputs: dict | None result: Any error: str | None workflow_definition: dict ``` ## Depends On - #224 (Infrastructure Setup) ## Acceptance Criteria - [ ] All 18 endpoints have OpenAPI decorators - [ ] Request/Response models documented - [ ] Query parameters documented - [ ] Path parameters documented - [ ] Error responses documented - [ ] Examples provided