{
  "openapi": "3.1.0",
  "info": {
    "title": "Exomations public API",
    "version": "1.0.0",
    "description": "The endpoints an outside system can call with an Exomations API key: start a flow, and the MCP server. Paths carry no version. Errors on the trigger endpoints are JSON with `error`, `code` and `message`. Human-readable reference: https://exomations.com/docs/api and https://exomations.com/docs/mcp."
  },
  "servers": [
    {
      "url": "https://exomations.com",
      "description": "Or your workspace's own domain, if it has one."
    }
  ],
  "tags": [
    {
      "name": "Trigger",
      "description": "Start a run of an active flow."
    },
    {
      "name": "MCP",
      "description": "The Model Context Protocol server for AI clients."
    }
  ],
  "paths": {
    "/api/trigger/{flowId}": {
      "post": {
        "operationId": "triggerFlow",
        "summary": "Trigger a flow",
        "description": "Start one run of an active flow with a JSON payload.\n\nSends the request body to the flow's Trigger step and records one run. The call answers at once with `202` and an execution ID; it never waits for the flow to finish. The flow must be active and belong to the key's workspace.\n\nSend an API key with the `execute` permission in the `X-Api-Key` header. Keys are created on the **API Keys** page of the app by an Admin or Owner; the API overview explains permissions, expiry and rotation.",
        "tags": [
          "Trigger"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "description": "The flow's ID. The flow must be active and belong to the key's workspace.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Webhook-Signature",
            "in": "header",
            "required": false,
            "description": "Required only when a signing secret is set for the workspace: the lowercase hex HMAC-SHA256 of the raw body. The other accepted formats are listed in the API overview.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Any JSON object, up to 8 MB. It becomes the run's trigger data: a field is read in the flow as `{{trigger.order_id}}`. The body is not checked against a schema.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              },
              "example": {
                "order_id": "1042",
                "customer": {
                  "phone": "+9665XXXXXXXX"
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. `status` says what happened: `queued` (the run waits for a worker), `held` (the workspace is past 120% of its monthly allowance; the run starts by itself after a top-up, an upgrade or the monthly reset) or `duplicate_suppressed` (the same body reached the same flow within 10 seconds and no second run was started; `executionId` is the first delivery's run, or `null` when it is not known).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TriggerAccepted"
                },
                "examples": {
                  "e1": {
                    "summary": "queued",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "queued"
                    }
                  },
                  "e2": {
                    "summary": "held",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "held",
                      "message": "Accepted and held: the workspace is over its monthly execution allowance. The run is recorded and starts automatically after a top-up or upgrade, or when the month resets."
                    }
                  },
                  "e3": {
                    "summary": "duplicate_suppressed",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "duplicate_suppressed",
                      "message": "An identical payload was received for this flow moments ago; this delivery was deduplicated."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The flow exists but is not active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Flow is not active",
                    "value": {
                      "error": "Flow is not active",
                      "code": "VALIDATION",
                      "message": "Flow is not active"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The `X-Api-Key` header is missing, or a signing secret is set and the signature is missing or does not match.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "API key required. Include X-Api-Key header.",
                    "value": {
                      "error": "API key required. Include X-Api-Key header.",
                      "code": "SESSION_EXPIRED",
                      "message": "API key required. Include X-Api-Key header."
                    }
                  },
                  "e2": {
                    "summary": "Webhook signature verification failed",
                    "value": {
                      "error": "Webhook signature verification failed",
                      "code": "SESSION_EXPIRED",
                      "message": "Webhook signature verification failed"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key is unknown, inactive or expired, it lacks `execute`, or the workspace is suspended.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Invalid or inactive API key",
                    "value": {
                      "error": "Invalid or inactive API key",
                      "code": "FORBIDDEN",
                      "message": "Invalid or inactive API key"
                    }
                  },
                  "e2": {
                    "summary": "API key expired",
                    "value": {
                      "error": "API key expired",
                      "code": "FORBIDDEN",
                      "message": "API key expired"
                    }
                  },
                  "e3": {
                    "summary": "API key lacks execute permission",
                    "value": {
                      "error": "API key lacks execute permission",
                      "code": "FORBIDDEN",
                      "message": "API key lacks execute permission"
                    }
                  },
                  "e4": {
                    "summary": "Tenant not found or suspended",
                    "value": {
                      "error": "Tenant not found or suspended",
                      "code": "FORBIDDEN",
                      "message": "Tenant not found or suspended"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No flow with this ID in the key's workspace. Flows of other workspaces also answer `404`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Flow not found",
                    "value": {
                      "error": "Flow not found",
                      "code": "NOT_FOUND",
                      "message": "Flow not found"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The body is over 8 MB, or it is nested more than 64 levels deep or has more than 500,000 keys, or it was sent compressed and expands far beyond its compressed size. A body over the size is refused before the flow is looked up and that answer has only a `message` field; the others answer `{ error, code, message }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooLarge"
                },
                "examples": {
                  "e1": {
                    "summary": "request entity too large",
                    "value": {
                      "message": "request entity too large"
                    }
                  },
                  "e2": {
                    "summary": "Payload nesting exceeds the depth limit of 64",
                    "value": {
                      "error": "Payload nesting exceeds the depth limit of 64",
                      "code": "PAYLOAD_TOO_LARGE",
                      "message": "Payload nesting exceeds the depth limit of 64"
                    }
                  },
                  "e3": {
                    "summary": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.",
                    "value": {
                      "error": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.",
                      "code": "PAYLOAD_TOO_LARGE",
                      "message": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many calls in a minute. Wait the number of seconds in the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Too many requests, please try again later",
                    "value": {
                      "error": "Too many requests, please try again later",
                      "code": "RATE_LIMIT",
                      "message": "Too many requests, please try again later"
                    }
                  },
                  "e2": {
                    "summary": "Rate limit exceeded for webhook triggers",
                    "value": {
                      "error": "Rate limit exceeded for webhook triggers",
                      "code": "RATE_LIMIT",
                      "message": "Rate limit exceeded for webhook triggers"
                    }
                  },
                  "e3": {
                    "summary": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly.",
                    "value": {
                      "error": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly.",
                      "code": "RATE_LIMIT",
                      "message": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The run could not be recorded. Retry; if it happens again, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Trigger failed",
                    "value": {
                      "error": "Trigger failed",
                      "code": "SERVER_ERROR",
                      "message": "Trigger failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/trigger/{tenantId}/{flowId}": {
      "post": {
        "operationId": "triggerFlowInWorkspace",
        "summary": "Trigger a flow (workspace in the path)",
        "description": "The same call with your workspace ID in the path.\n\nWorks exactly like Trigger a flow, with one more check: the workspace ID in the path must be the workspace the key belongs to, or the call is refused with `403`.\n\nSend an API key with the `execute` permission in the `X-Api-Key` header. Keys are created on the **API Keys** page of the app by an Admin or Owner; the API overview explains permissions, expiry and rotation.",
        "tags": [
          "Trigger"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "description": "Your workspace ID. It must be the workspace the API key belongs to.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "description": "The flow's ID. The flow must be active and belong to the key's workspace.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Webhook-Signature",
            "in": "header",
            "required": false,
            "description": "Required only when a signing secret is set for the workspace: the lowercase hex HMAC-SHA256 of the raw body. The other accepted formats are listed in the API overview.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Any JSON object, up to 8 MB. It becomes the run's trigger data: a field is read in the flow as `{{trigger.order_id}}`. The body is not checked against a schema.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              },
              "example": {
                "order_id": "1042",
                "customer": {
                  "phone": "+9665XXXXXXXX"
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. `status` says what happened: `queued` (the run waits for a worker), `held` (the workspace is past 120% of its monthly allowance; the run starts by itself after a top-up, an upgrade or the monthly reset) or `duplicate_suppressed` (the same body reached the same flow within 10 seconds and no second run was started; `executionId` is the first delivery's run, or `null` when it is not known).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TriggerAccepted"
                },
                "examples": {
                  "e1": {
                    "summary": "queued",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "queued"
                    }
                  },
                  "e2": {
                    "summary": "held",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "held",
                      "message": "Accepted and held: the workspace is over its monthly execution allowance. The run is recorded and starts automatically after a top-up or upgrade, or when the month resets."
                    }
                  },
                  "e3": {
                    "summary": "duplicate_suppressed",
                    "value": {
                      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
                      "status": "duplicate_suppressed",
                      "message": "An identical payload was received for this flow moments ago; this delivery was deduplicated."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The flow exists but is not active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Flow is not active",
                    "value": {
                      "error": "Flow is not active",
                      "code": "VALIDATION",
                      "message": "Flow is not active"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The `X-Api-Key` header is missing, or a signing secret is set and the signature is missing or does not match.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "API key required. Include X-Api-Key header.",
                    "value": {
                      "error": "API key required. Include X-Api-Key header.",
                      "code": "SESSION_EXPIRED",
                      "message": "API key required. Include X-Api-Key header."
                    }
                  },
                  "e2": {
                    "summary": "Webhook signature verification failed",
                    "value": {
                      "error": "Webhook signature verification failed",
                      "code": "SESSION_EXPIRED",
                      "message": "Webhook signature verification failed"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key is unknown, inactive or expired, it lacks `execute`, the workspace ID in the path is not the key's workspace, or the workspace is suspended.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Invalid or inactive API key",
                    "value": {
                      "error": "Invalid or inactive API key",
                      "code": "FORBIDDEN",
                      "message": "Invalid or inactive API key"
                    }
                  },
                  "e2": {
                    "summary": "API key expired",
                    "value": {
                      "error": "API key expired",
                      "code": "FORBIDDEN",
                      "message": "API key expired"
                    }
                  },
                  "e3": {
                    "summary": "API key lacks execute permission",
                    "value": {
                      "error": "API key lacks execute permission",
                      "code": "FORBIDDEN",
                      "message": "API key lacks execute permission"
                    }
                  },
                  "e4": {
                    "summary": "API key does not match tenant",
                    "value": {
                      "error": "API key does not match tenant",
                      "code": "FORBIDDEN",
                      "message": "API key does not match tenant"
                    }
                  },
                  "e5": {
                    "summary": "Tenant not found or suspended",
                    "value": {
                      "error": "Tenant not found or suspended",
                      "code": "FORBIDDEN",
                      "message": "Tenant not found or suspended"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No flow with this ID in the key's workspace. Flows of other workspaces also answer `404`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Flow not found",
                    "value": {
                      "error": "Flow not found",
                      "code": "NOT_FOUND",
                      "message": "Flow not found"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The body is over 8 MB, or it is nested more than 64 levels deep or has more than 500,000 keys, or it was sent compressed and expands far beyond its compressed size. A body over the size is refused before the flow is looked up and that answer has only a `message` field; the others answer `{ error, code, message }`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooLarge"
                },
                "examples": {
                  "e1": {
                    "summary": "request entity too large",
                    "value": {
                      "message": "request entity too large"
                    }
                  },
                  "e2": {
                    "summary": "Payload nesting exceeds the depth limit of 64",
                    "value": {
                      "error": "Payload nesting exceeds the depth limit of 64",
                      "code": "PAYLOAD_TOO_LARGE",
                      "message": "Payload nesting exceeds the depth limit of 64"
                    }
                  },
                  "e3": {
                    "summary": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.",
                    "value": {
                      "error": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.",
                      "code": "PAYLOAD_TOO_LARGE",
                      "message": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many calls in a minute. Wait the number of seconds in the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Too many requests, please try again later",
                    "value": {
                      "error": "Too many requests, please try again later",
                      "code": "RATE_LIMIT",
                      "message": "Too many requests, please try again later"
                    }
                  },
                  "e2": {
                    "summary": "Rate limit exceeded for webhook triggers",
                    "value": {
                      "error": "Rate limit exceeded for webhook triggers",
                      "code": "RATE_LIMIT",
                      "message": "Rate limit exceeded for webhook triggers"
                    }
                  },
                  "e3": {
                    "summary": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly.",
                    "value": {
                      "error": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly.",
                      "code": "RATE_LIMIT",
                      "message": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The run could not be recorded. Retry; if it happens again, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "e1": {
                    "summary": "Trigger failed",
                    "value": {
                      "error": "Trigger failed",
                      "code": "SERVER_ERROR",
                      "message": "Trigger failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP server (JSON-RPC 2.0)",
        "description": "One JSON-RPC 2.0 request per POST, one JSON response; no event stream and no session. Methods: `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/*`. Tool failures are normal results with `isError: true`; protocol errors use the JSON-RPC `error` object. Tools:\n\n- `exo_<name>_<id8>` (execute): Each active flow is a tool. Calling it starts one run of that flow.\n- `exo_list_executions` (execute): Recent runs of one flow, without their data.\n- `exo_get_execution` (execute): One run in full: status, timing, trigger data and every step's input, output and error.\n- `exo_get_execution_step` (execute): One step of one run, with its full stored input and output.\n- `exo_search_apps` (build): Search the app catalogue, or read one app's operations.\n- `exo_get_node_types` (build): The step types a flow can use, with their settings, outputs and plan.\n- `exo_list_flows` (build): Every flow in the workspace, with its status and trigger type.\n- `exo_get_flow` (build): One flow's definition and settings, with secrets masked.\n- `exo_validate_flow` (build): Check a flow definition without saving it.\n- `exo_create_flow` (build): Create a new flow. It is always saved as a draft.\n- `exo_update_flow` (build): Change a flow's definition, name or description.\n- `exo_activate_flow` (build): Switch on a flow in staging, after the same checks as the app.",
        "tags": [
          "MCP"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "exo_overdue_invoice_reminders_7a17617d",
                  "arguments": {
                    "payload": {
                      "customer_id": "C-204"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC response (a result, or an error object for a protocol error).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "A notification (`notifications/initialized`, `notifications/cancelled`): no body."
          },
          "400": {
            "description": "The body is not valid JSON (JSON-RPC code -32700).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "401": {
            "description": "No credentials, or an OAuth access token that is expired or not recognised (JSON-RPC code -32001). Carries a `WWW-Authenticate` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid, inactive or expired key, a missing permission, or a suspended workspace (JSON-RPC code -32001).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many calls in a minute. Wait the number of seconds in `Retry-After`.",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "An Exomations API key (exo_ followed by 64 hex characters)."
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "MCP only: an API key, or an OAuth 2.0 access token for clients that cannot send a custom header."
      }
    },
    "schemas": {
      "TriggerAccepted": {
        "type": "object",
        "required": [
          "executionId",
          "status"
        ],
        "properties": {
          "executionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "held",
              "duplicate_suppressed"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, for example FORBIDDEN or RATE_LIMIT."
          },
          "message": {
            "type": "string",
            "description": "The same text as error."
          }
        }
      },
      "TooLarge": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {}
            }
          }
        }
      }
    }
  }
}