API referenceAgent spec
Import workflow from Agent Spec JSON
Convert an Agent Spec flow or document to a FlowDrop workflow. The conversion: - Maps Agent Spec component types to FlowDrop node types - Merges control_flow_connections and data_flow_connections into unified edges - Auto-layouts nodes if no position metadata is present - Preserves Agent Spec component_type in FlowDrop extensions This is the Agent Spec counterpart of the FlowDrop-native `POST /workflows/import` under **Import and Export**.
AuthorizationBearer <token>
JWT token for authentication
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Agent Spec Flow — a directed, potentially cyclic graph of nodes. Flows function as "subroutines" encapsulating repeatable processes. They separate control-flow (execution order) from data-flow (data routing).
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/workflows/import/agentspec" \ -H "Content-Type: application/json" \ -d '{ "component_type": "flow", "name": "document_processing", "start_node": "start", "nodes": [ { "component_type": "start_node", "name": "process_input" } ], "control_flow_connections": [ { "name": "start_to_process", "from_node": "start", "to_node": "process_input" } ] }'{ "success": true, "message": "string", "error": "string", "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "My AI Workflow", "description": "string", "nodes": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "calculator", "position": { "x": 100, "y": 200 }, "deletable": true, "data": { "label": "Math Calculator", "config": { "instanceTitle": "Email Summarizer", "instanceDescription": "Summarizes incoming emails into 3 bullet points", "instanceBadge": "LLM", "nodeType": "simple", "model": "gpt-4o-mini", "temperature": 0.7, "maxTokens": 1000, "apiKey": "sk-...", "dynamicInputs": [ { "name": "extra_data", "label": "Extra Data", "dataType": "json", "required": false } ], "dynamicOutputs": [ { "name": "result", "label": "Result", "dataType": "string" } ], "branches": [ { "name": "success", "label": "Success", "condition": "status === 200" }, { "name": "error", "label": "Error", "isDefault": true } ] }, "metadata": { "node_type_id": "calculator", "name": "Calculator", "type": "note", "supportedTypes": [ "note" ], "description": "Perform mathematical operations on input data", "category": "processing", "version": "1.0.0", "icon": "mdi:calculator", "color": "#3b82f6", "badge": "API", "portDataType": "trigger", "inputs": [ { "id": "json", "name": "JSON Response", "type": "input", "dataType": "mixed", "required": false, "description": "Parsed JSON response from the HTTP request", "defaultValue": null, "exposedByDefault": true, "displayOrder": 0, "schema": { "type": "object", "properties": { "user": { "type": "object", "title": "User", "description": "User information", "properties": { "id": { "type": "integer", "description": "User ID" }, "name": { "type": "string", "description": "User full name" }, "email": { "type": "string", "description": "User email address" }, "address": { "type": "object", "title": "Address", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } }, "orders": { "type": "array", "title": "Orders", "description": "List of user orders", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" } } } } } } } ], "outputs": [ { "id": "json", "name": "JSON Response", "type": "input", "dataType": "mixed", "required": false, "description": "Parsed JSON response from the HTTP request", "defaultValue": null, "exposedByDefault": true, "displayOrder": 0, "schema": { "type": "object", "properties": { "user": { "type": "object", "title": "User", "description": "User information", "properties": { "id": { "type": "integer", "description": "User ID" }, "name": { "type": "string", "description": "User full name" }, "email": { "type": "string", "description": "User email address" }, "address": { "type": "object", "title": "Address", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } }, "orders": { "type": "array", "title": "Orders", "description": "List of user orders", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" } } } } } } } ], "configSchema": { "type": "object", "properties": { "property1": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ null ], "oneOf": [ { "const": "string", "title": "string", "description": "string" } ], "multiple": true, "minimum": 0, "maximum": 0, "step": 0, "minLength": 0, "maxLength": 0, "pattern": "string", "placeholder": "string", "format": "multiline", "variables": { "ports": [ "data" ], "showHints": true, "includePortName": false }, "x-display-order": -2, "items": {}, "minItems": 0, "maxItems": 0, "properties": { "property1": {}, "property2": {} }, "autocomplete": { "url": "/api/users/search", "queryParam": "q", "minChars": 0, "debounceMs": 300, "fetchOnFocus": false, "labelField": "label", "valueField": "value", "allowFreeText": false, "multiple": false, "params": { "property1": "string", "property2": "string" } }, "readOnly": true, "height": "300px", "darkTheme": true, "autoFormat": true, "showToolbar": true, "showStatusBar": true, "spellChecker": false, "placeholderExample": "Hello {{ name }}, your order #{{ order_id }} is ready!" }, "property2": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ null ], "oneOf": [ { "const": "string", "title": "string", "description": "string" } ], "multiple": true, "minimum": 0, "maximum": 0, "step": 0, "minLength": 0, "maxLength": 0, "pattern": "string", "placeholder": "string", "format": "multiline", "variables": { "ports": [ "data" ], "showHints": true, "includePortName": false }, "x-display-order": -2, "items": {}, "minItems": 0, "maxItems": 0, "properties": { "property1": {}, "property2": {} }, "autocomplete": { "url": "/api/users/search", "queryParam": "q", "minChars": 0, "debounceMs": 300, "fetchOnFocus": false, "labelField": "label", "valueField": "value", "allowFreeText": false, "multiple": false, "params": { "property1": "string", "property2": "string" } }, "readOnly": true, "height": "300px", "darkTheme": true, "autoFormat": true, "showToolbar": true, "showStatusBar": true, "spellChecker": false, "placeholderExample": "Hello {{ name }}, your order #{{ order_id }} is ready!" } }, "required": [ "string" ], "additionalProperties": false }, "tags": [ "math", "calculation", "processing" ], "formats": [ "agentspec" ], "extensions": { "ui": { "style": { "opacity": 0.8 } }, "agentspec:component_type": "llm_node", "myapp:analytics": { "trackUsage": true, "customField": "value" } } }, "isProcessing": true, "error": "string", "executionInfo": { "status": "idle", "executionCount": 5, "lastExecuted": "2019-08-24T14:15:22Z", "lastExecutionDuration": 1500, "lastError": "string", "isExecuting": true }, "extensions": { "ui": { "style": { "opacity": 0.8 } }, "agentspec:component_type": "llm_node", "myapp:analytics": { "trackUsage": true, "customField": "value" } } } } ], "edges": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "source": "07b8e003-7027-443f-88b0-24a5eb1cc68b", "target": "65a17d54-9c67-4477-8b80-d3f97e165aa5", "sourceHandle": "string", "targetHandle": "string", "type": "default", "selectable": true, "deletable": true, "data": { "label": "string", "condition": "string", "metadata": { "edgeType": "trigger", "sourcePortDataType": "string" }, "isToolConnection": true, "targetNodeType": "string", "targetCategory": "string" } } ], "metadata": { "schemaVersion": "1.0.0", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "author": "admin", "tags": [ "ai", "production" ], "versionId": "string", "updateNumber": 0, "format": "flowdrop" }, "config": {}, "interface": { "inputs": [ { "id": "customerName", "name": "string", "description": "string", "dataType": "mixed", "required": true, "defaultValue": null, "examples": [ null ], "schema": { "type": "object", "properties": { "user": { "type": "object", "title": "User", "description": "User information", "properties": { "id": { "type": "integer", "description": "User ID" }, "name": { "type": "string", "description": "User full name" }, "email": { "type": "string", "description": "User email address" }, "address": { "type": "object", "title": "Address", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } }, "orders": { "type": "array", "title": "Orders", "description": "List of user orders", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" } } } } } }, "bindings": [ { "nodeId": "959356e3-6168-4a92-b4a5-b9d462be6177", "portId": "string" } ], "meta": {} } ], "outputs": [ { "id": "customerName", "name": "string", "description": "string", "dataType": "mixed", "required": true, "defaultValue": null, "examples": [ null ], "schema": { "type": "object", "properties": { "user": { "type": "object", "title": "User", "description": "User information", "properties": { "id": { "type": "integer", "description": "User ID" }, "name": { "type": "string", "description": "User full name" }, "email": { "type": "string", "description": "User email address" }, "address": { "type": "object", "title": "Address", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } }, "orders": { "type": "array", "title": "Orders", "description": "List of user orders", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" } } } } } }, "bindings": [ { "nodeId": "959356e3-6168-4a92-b4a5-b9d462be6177", "portId": "string" } ], "meta": {} } ] } }}Export workflow as Agent Spec JSON GET
Convert a FlowDrop workflow to Agent Spec format and return it. The conversion: - Maps FlowDrop node types to Agent Spec component types - Splits unified edges into control_flow_connections and data_flow_connections - Stores FlowDrop-specific data (positions, dynamic ports) in metadata extensions - Validates the workflow for Agent Spec compatibility before export This is the Agent Spec counterpart of the FlowDrop-native `GET /workflows/{id}/export` under **Import and Export**.
Validate workflow for Agent Spec export GET
Check if a FlowDrop workflow can be exported as Agent Spec. Returns validation errors and warnings without performing the export. Checks include: - Exactly one start node (terminal/trigger type) - At least one end node (terminal/output type) - Gateway nodes have branches defined - All nodes are reachable from start This checks Agent Spec export compatibility only. For general workflow validation before execution, see `POST /workflows/validate` under **Validation**.