# 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"}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.workfx.ai/workfx-companion-agent-knowledge/developer-docs/api-reference/agent/agent-flows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.