For tools and AI agents: this page as Markdown · the public OpenAPI file
Description
The definition is checked before anything is saved: its size (up to 2 MB, 40 levels deep and 20,000 keys), its structure, the platform's staging checks and your plan. If a check fails, nothing is saved and the problems are returned. The flow goes into projectId, or into your workspace's first project. A workspace at its plan's flow limit cannot create more. Government sign-off settings sent by the client are dropped: only a person can switch them on in the app.
The new flow is a draft. exo_activate_flow refuses flows whose environment is production, which is where every new flow starts, so a person reviews a new flow in the app before it runs.
Permission
Needs an API key or OAuth connection with the build permission.
Input
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Flow name. |
definition | object | Yes | The flow definition { nodes, edges }. |
description | string | No | Optional flow description. |
projectId | string | No | Optional project id. Defaults to your tenant's first project. |
triggerType | string: webhook, manual, scheduled, form, poll_trigger, email_trigger, voice_call_ended, whatsapp_message | No | Optional trigger type (default 'webhook'). |
Returns
saved: true, flowId, status: "draft" and warnings. When a government sign-off was dropped, governmentConfirmationIgnored lists the steps.
Plan check
Each step type belongs to a plan. A create or update that adds a step your workspace's plan does not include is refused before anything is saved, with code: "PLAN_REQUIRED", the plan it needs (requiredPlan), the steps involved (steps) and the message in English, Arabic and Chinese (messages). exo_get_node_types marks which steps your plan includes, and exo_validate_flow reports them as warnings.
{
"saved": false,
"code": "PLAN_REQUIRED",
"upgradeRequired": true,
"currentPlan": "starter",
"requiredPlan": "pro",
"steps": [
{
"nodeId": "sftp_1",
"type": "sftp",
"label": "SFTP / FTP Files",
"family": "advanced_integrations",
"requiredPlan": "pro"
}
],
"messages": {
"en": "Your Starter plan doesn't include these steps: SFTP / FTP Files. They are part of the Professional plan. Nothing was created. Upgrade to Professional, or use steps your plan includes.",
"ar": "…",
"zh": "…"
}
}Errors
Returned as a normal result with isError: true:
`name` is required.`triggerType` must be one of: <types> (default webhook). Nothing was created.`definition` object is required.`definition` rejected: <reason>.Flow NOT created — <n> error(s), <n> warning(s). Fix the errors and retry: <list>Flow NOT created — the definition failed the platform staging verifier: <violations>. Fix these issues and retry.Project "<projectId>" not found in your tenant.Your tenant has no projects yet. Create a project in the Exomations UI first, then retry.Maximum flow limit (<n>) reached for your plan. Delete a flow or upgrade.Flow NOT created — <reason> (step types: <types>). …
Returned as a JSON-RPC error:
| Code | HTTP | Message |
|---|---|---|
| -32001 | 403 | API key lacks the 'build' permission required for flow authoring tools |
Messages are shown exactly as the server sends them, in English. A value in angle brackets is filled in at run time.
Examples
Example call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "exo_create_flow",
"arguments": {
"name": "Post new orders",
"definition": {
"nodes": [
{
"id": "trigger_1",
"type": "trigger",
"position": {
"x": 0,
"y": 0
},
"data": {
"nodeType": "trigger",
"label": "Webhook",
"config": {}
}
},
{
"id": "http_1",
"type": "http_request",
"position": {
"x": 260,
"y": 0
},
"data": {
"nodeType": "http_request",
"label": "Post order",
"config": {
"url": "https://example.com/orders",
"method": "POST",
"body": "{{trigger.order_id}}"
}
}
}
],
"edges": [
{
"id": "e1",
"source": "trigger_1",
"target": "http_1"
}
]
}
}
}
}curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"exo_create_flow","arguments":{"name":"Post new orders","definition":{"nodes":[{"id":"trigger_1","type":"trigger","position":{"x":0,"y":0},"data":{"nodeType":"trigger","label":"Webhook","config":{}}},{"id":"http_1","type":"http_request","position":{"x":260,"y":0},"data":{"nodeType":"http_request","label":"Post order","config":{"url":"https://example.com/orders","method":"POST","body":"{{trigger.order_id}}"}}}],"edges":[{"id":"e1","source":"trigger_1","target":"http_1"}]}}}}'Example result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Flow \"Post new orders\" created as a DRAFT (id=7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61). A person reviews and activates it in the Exomations app; exo_activate_flow refuses a flow whose environment is production, which is where every new flow starts.\n{ ... }"
}
],
"structuredContent": {
"saved": true,
"flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
"status": "draft",
"warnings": []
},
"isError": false
}
}Example values. In content, the text after the summary line is the same data as structuredContent.