# Agent Flows

## POST /admin/api/v2/tools/{tool\_id}/flows

> Create Or Update Draft Flow Tool

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Tool"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/tools/{tool_id}/flows":{"post":{"summary":"Create Or Update Draft Flow Tool","deprecated":false,"description":"","operationId":"create_or_update_draft_flow_tool_admin_api_v2_tools__tool_id__flows_post","tags":["Tool"],"parameters":[{"name":"tool_id","in":"path","description":"Tool id","required":true,"schema":{"type":"string","format":"uuid","description":"Tool id","title":"Tool Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowDraftVersionCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowDefinitionEntity"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"FlowDraftVersionCreateRequest":{"properties":{"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By"},"created_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Role"},"updated_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Role"},"created_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Time"},"updated_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated Time"},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"The ID of the flow this definition belongs to"},"owner_type":{"anyOf":[{"type":"object","properties":{}},{"type":"null"}],"description":"Type of flow [flow, tool]"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode","description":"Flow mode, e.g., chat or job"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Version of the flow"},"graph":{"type":"object","title":"Graph","description":"Flow graph","default":{},"properties":{}},"features":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Features","description":"Additional features for the flow"},"flow_variables":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Flow Variables","description":"Environment variables for the flow"},"conversation_variables":{"anyOf":[{"additionalProperties":{"type":"object","properties":{}},"type":"object"},{"type":"null"}],"title":"Conversation Variables","description":"Conversation variables for the flow"}},"type":"object","title":"FlowDraftVersionCreateRequest"},"FlowDefinitionEntity":{"properties":{"created_by":{"type":"string","title":"Created By","description":"ID of the creator"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"ID of the last updater"},"created_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Role"},"updated_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Role"},"created_time":{"type":"string","format":"date-time","title":"Created Time","description":"Timestamp of creation"},"updated_time":{"type":"string","format":"date-time","title":"Updated Time","description":"Timestamp of last update"},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"The ID of the flow this definition belongs to"},"owner_type":{"anyOf":[{"$ref":"#/components/schemas/FlowOwnerType"},{"type":"null"}],"description":"Type of flow [flow, tool]"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode","description":"Flow mode, e.g., chat or job"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Version of the flow"},"graph":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Graph","description":"Flow graph"},"features":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Features","description":"Additional features for the flow"},"flow_variables":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Flow Variables","description":"Environment variables for the flow"},"conversation_variables":{"anyOf":[{"additionalProperties":{"type":"object","properties":{}},"type":"object"},{"type":"null"}],"title":"Conversation Variables","description":"Conversation variables for the flow"},"id":{"type":"string","title":"Id","description":"The ID of the created FlowDefinitionDO"},"tenant_id":{"type":"string","title":"Tenant Id","description":"Tenant ID"},"tenant_unit_id":{"type":"string","title":"Tenant Unit Id","description":"Tenant Unit ID"}},"type":"object","required":["created_by","id","tenant_id","tenant_unit_id"],"title":"FlowDefinitionEntity","description":"Full flow model with additional fields used for responses."},"FlowOwnerType":{"type":"string","enum":["agent","multi-agent","tool"],"title":"FlowOwnerType"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Get Draft

> Get the DRAFT version of a flow

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Flows Versions"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/agents/{agent_id}/flows/draft":{"get":{"summary":"Get Draft","deprecated":false,"description":"Get the DRAFT version of a flow","operationId":"get_draft_admin_api_v2_agents__agent_id__flows_draft_get","tags":["Flows Versions"],"parameters":[{"name":"agent_id","in":"path","description":"","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowDefinitionEntity"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"FlowDefinitionEntity":{"properties":{"created_by":{"type":"string","title":"Created By","description":"ID of the creator"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"ID of the last updater"},"created_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Role"},"updated_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Role"},"created_time":{"type":"string","format":"date-time","title":"Created Time","description":"Timestamp of creation"},"updated_time":{"type":"string","format":"date-time","title":"Updated Time","description":"Timestamp of last update"},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"The ID of the flow this definition belongs to"},"owner_type":{"anyOf":[{"$ref":"#/components/schemas/FlowOwnerType"},{"type":"null"}],"description":"Type of flow [flow, tool]"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode","description":"Flow mode, e.g., chat or job"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Version of the flow"},"graph":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Graph","description":"Flow graph"},"features":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Features","description":"Additional features for the flow"},"flow_variables":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Flow Variables","description":"Environment variables for the flow"},"conversation_variables":{"anyOf":[{"additionalProperties":{"type":"object","properties":{}},"type":"object"},{"type":"null"}],"title":"Conversation Variables","description":"Conversation variables for the flow"},"id":{"type":"string","title":"Id","description":"The ID of the created FlowDefinitionDO"},"tenant_id":{"type":"string","title":"Tenant Id","description":"Tenant ID"},"tenant_unit_id":{"type":"string","title":"Tenant Unit Id","description":"Tenant Unit ID"}},"type":"object","required":["created_by","id","tenant_id","tenant_unit_id"],"title":"FlowDefinitionEntity","description":"Full flow model with additional fields used for responses."},"FlowOwnerType":{"type":"string","enum":["agent","multi-agent","tool"],"title":"FlowOwnerType"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Publish

> Publish the current DRAFT version as a formal version

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Flows Versions"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/agents/{agent_id}/flows/publish":{"post":{"summary":"Publish","deprecated":false,"description":"Publish the current DRAFT version as a formal version","operationId":"publish_admin_api_v2_agents__agent_id__flows_publish_post","tags":["Flows Versions"],"parameters":[{"name":"agent_id","in":"path","description":"","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowVersionPublishResponse"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"FlowVersionPublishResponse":{"properties":{"created_by":{"type":"string","title":"Created By","description":"ID of the creator"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"ID of the last updater"},"created_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Role"},"updated_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Role"},"created_time":{"type":"string","format":"date-time","title":"Created Time","description":"Timestamp of creation"},"updated_time":{"type":"string","format":"date-time","title":"Updated Time","description":"Timestamp of last update"},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"The ID of the flow this definition belongs to"},"owner_type":{"anyOf":[{"$ref":"#/components/schemas/FlowOwnerType"},{"type":"null"}],"description":"Type of flow [flow, tool]"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode","description":"Flow mode, e.g., chat or job"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Version of the flow"},"graph":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Graph","description":"Flow graph"},"features":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Features","description":"Additional features for the flow"},"flow_variables":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Flow Variables","description":"Environment variables for the flow"},"conversation_variables":{"anyOf":[{"additionalProperties":{"type":"object","properties":{}},"type":"object"},{"type":"null"}],"title":"Conversation Variables","description":"Conversation variables for the flow"},"id":{"type":"string","title":"Id","description":"The ID of the created FlowDefinitionDO"},"tenant_id":{"type":"string","title":"Tenant Id","description":"Tenant ID"},"tenant_unit_id":{"type":"string","title":"Tenant Unit Id","description":"Tenant Unit ID"}},"type":"object","required":["created_by","id","tenant_id","tenant_unit_id"],"title":"FlowVersionPublishResponse","description":"Response model for the created FlowDefinitionDO."},"FlowOwnerType":{"type":"string","enum":["agent","multi-agent","tool"],"title":"FlowOwnerType"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## List Versions

> Get a list of all versions for a specific flow

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Flows Versions"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/agents/{agent_id}/flows":{"get":{"summary":"List Versions","deprecated":false,"description":"Get a list of all versions for a specific flow","operationId":"list_versions_admin_api_v2_agents__agent_id__flows_get","tags":["Flows Versions"],"parameters":[{"name":"agent_id","in":"path","description":"Agent id","required":true,"schema":{"type":"string","format":"uuid","description":"Agent id","title":"Agent Id"}},{"name":"page_num","in":"query","description":"Current page number","required":false,"schema":{"type":"integer","description":"Current page number","default":1,"title":"Page Num"}},{"name":"page_size","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","description":"Items per page","default":20,"title":"Page Size"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowVersionListResponse"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"FlowVersionListResponse":{"properties":{"page_num":{"type":"integer","title":"Page Num","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of items per page"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of flows"},"has_next_page":{"type":"boolean","title":"Has Next Page","description":"Whether there is a next page"},"data":{"items":{"type":"object","properties":{}},"type":"array","title":"Data","description":"List of flow_definitions"}},"type":"object","required":["page_num","page_size","total_count","has_next_page","data"],"title":"FlowVersionListResponse","description":"Response model for the created flowDefinition."},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Run Draft Workflow

> Run the draft version of the workflow

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Flow Runs"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/agents/{agent_id}/flows/draft/runs":{"post":{"summary":"Run Draft Workflow","deprecated":false,"description":"Run the draft version of the workflow","operationId":"run_draft_workflow_admin_api_v2_agents__agent_id__flows_draft_runs_post","tags":["Flow Runs"],"parameters":[{"name":"agent_id","in":"path","description":"","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AgentChatInvokeRequest"},{"$ref":"#/components/schemas/AgentJobInvokeRequest"}],"title":"Flow Run Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"string"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"AgentChatInvokeRequest":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","default":""},"inputs":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Inputs","description":"Input variables"},"streaming":{"type":"boolean","title":"Streaming","default":false},"files":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Files","default":[]},"response_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Type","default":"wfx"},"wfx_context":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Wfx Context","default":{}},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id"}},"type":"object","title":"AgentChatInvokeRequest"},"AgentJobInvokeRequest":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","default":""},"inputs":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Inputs","description":"Input variables"},"streaming":{"type":"boolean","title":"Streaming","default":false},"files":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Files","default":[]},"response_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Type","default":"wfx"},"wfx_context":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Wfx Context","default":{}},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id"}},"type":"object","title":"AgentJobInvokeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```