{ "openapi": "3.1.0", "info": { "title": "Flows API", "version": "1.2.0", "description": "Flow collections, nodes and workflows in the QuivaWorks hub: create, publish, run, resume, monitor, and the integration OAuth connections flows use." }, "servers": [ { "url": "https://api.quiva.ai", "description": "Production API server" } ], "paths": { "/hub/collections": { "post": { "tags": [ "Collections" ], "summary": "Create a new collection", "description": "Creates a new collection for organizing nodes or workflows", "operationId": "createCollection", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionRequest" }, "examples": { "NodeCollection": { "summary": "Create a node collection", "value": { "name": "Payment Processing Nodes", "collection_type": "node", "description": "Collection of reusable payment processing node templates" } }, "WorkflowCollection": { "summary": "Create a workflow collection", "value": { "name": "Order Management Flows", "collection_type": "workflow", "description": "Workflows for handling order lifecycle" } }, "MinimalCollection": { "summary": "Create collection with minimal fields", "value": { "name": "Utilities", "collection_type": "node" } } } } } }, "responses": { "201": { "description": "Collection created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionResponse" }, "examples": { "NodeCollectionCreated": { "summary": "Node collection created", "value": { "subject": "ms.hub.config.collection.node.805092869", "name": "Payment Processing Nodes", "collection_type": "node", "topic": "805092869", "description": "Collection of reusable payment processing node templates", "modified": 1748533179 } }, "WorkflowCollectionCreated": { "summary": "Workflow collection created", "value": { "subject": "ms.hub.config.collection.workflow.1508781670", "name": "Order Management Flows", "collection_type": "workflow", "topic": "1508781670", "description": "Workflows for handling order lifecycle", "modified": 1748533200 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NameRequired": { "value": { "error": "a name is required" } }, "InvalidType": { "value": { "error": "invalid collection type. Valid types are: node, workflow" } } } } } }, "409": { "description": "Collection already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "collection exists:ms.hub.config.collection.node.1234567890" } } } } } }, "get": { "tags": [ "Collections" ], "summary": "List collections", "description": "Retrieves a list of collections", "operationId": "listCollections", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/queryCollectionType" } ], "responses": { "200": { "description": "Collection retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "results_total" ], "properties": { "results": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of results", "items": { "$ref": "#/components/schemas/GetCollectionResponse" } }, "results_total": { "type": "integer", "description": "Number of results" } } } } }, "examples": { "AllCollections": { "summary": "List all collections (no filter)", "value": { "results_total": 4, "results": [ { "collection_type": "node", "description": "Payment processing node templates", "modified": 1748533179, "name": "Payment Nodes", "sequence": 16, "subject": "ms.hub.config.collection.node.805092869", "topic": "805092869", "type": "created" }, { "collection_type": "node", "description": "Utility functions for data transformation", "modified": 1748533200, "name": "Data Transform Nodes", "sequence": 24, "subject": "ms.hub.config.collection.node.1025086208", "topic": "1025086208", "type": "updated" }, { "collection_type": "workflow", "description": "Order lifecycle management", "modified": 1748533250, "name": "Order Flows", "sequence": 31, "subject": "ms.hub.config.collection.workflow.1508781670", "topic": "1508781670", "type": "created" }, { "collection_type": "workflow", "description": "", "modified": 1748533300, "name": "Notification Flows", "sequence": 45, "subject": "ms.hub.config.collection.workflow.2098761234", "topic": "2098761234", "type": "created" } ] } }, "NodeCollectionsOnly": { "summary": "List node collections only", "value": { "results_total": 2, "results": [ { "collection_type": "node", "description": "Payment processing node templates", "modified": 1748533179, "name": "Payment Nodes", "sequence": 16, "subject": "ms.hub.config.collection.node.805092869", "topic": "805092869", "type": "created" }, { "collection_type": "node", "description": "Utility functions for data transformation", "modified": 1748533200, "name": "Data Transform Nodes", "sequence": 24, "subject": "ms.hub.config.collection.node.1025086208", "topic": "1025086208", "type": "updated" } ] } }, "WorkflowCollectionsOnly": { "summary": "List workflow collections only", "value": { "results_total": 2, "results": [ { "collection_type": "workflow", "description": "Order lifecycle management", "modified": 1748533250, "name": "Order Flows", "sequence": 31, "subject": "ms.hub.config.collection.workflow.1508781670", "topic": "1508781670", "type": "created" }, { "collection_type": "workflow", "description": "", "modified": 1748533300, "name": "Notification Flows", "sequence": 45, "subject": "ms.hub.config.collection.workflow.2098761234", "topic": "2098761234", "type": "created" } ] } }, "EmptyResult": { "summary": "No collections found", "value": { "results_total": 0, "results": [] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } } }, "/hub/collections/{collection_type}/{collection_topic}": { "parameters": [ { "$ref": "#/components/parameters/collectionType" }, { "$ref": "#/components/parameters/collectionTopic" } ], "get": { "tags": [ "Collections" ], "summary": "Get a collection", "description": "Retrieves a specific collection", "operationId": "getCollection", "x-resource-type": "service", "responses": { "200": { "description": "Collection retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCollectionResponse" }, "examples": { "NodeCollection": { "summary": "Retrieved node collection", "value": { "collection_type": "node", "description": "Payment processing node templates", "modified": 1748533179, "name": "Payment Nodes", "sequence": 16, "subject": "ms.hub.config.collection.node.805092869", "topic": "805092869", "type": "created" } }, "WorkflowCollection": { "summary": "Retrieved workflow collection", "value": { "collection_type": "workflow", "description": "Order lifecycle management workflows", "modified": 1748533250, "name": "Order Flows", "sequence": 124, "subject": "ms.hub.config.collection.workflow.1508781670", "topic": "1508781670", "type": "updated" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } }, "patch": { "tags": [ "Collections" ], "summary": "Update a Workflow or Node collection", "description": "Updates an existing collection's properties", "operationId": "updateFlowOrNodeCollection", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionRequest" }, "examples": { "UpdateDescription": { "summary": "Update collection description", "value": { "subject": "ms.hub.config.collection.node.805092869", "description": "Updated: Payment and billing node templates for all transaction types" } }, "ClearDescription": { "summary": "Clear collection description", "value": { "subject": "ms.hub.config.collection.workflow.1508781670", "description": "" } } } } } }, "responses": { "200": { "description": "Collection updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SubjectRequired": { "value": { "error": "a subject is required" } } } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "collection does not exists" } } } } } }, "delete": { "tags": [ "Collections" ], "summary": "Delete a collection", "description": "Deletes a specific collection by subject", "operationId": "deleteCollection", "x-resource-type": "service", "parameters": [ { "name": "move_resources_to_collection", "in": "query", "description": "A topic of another collection where resources can be moved", "required": true, "schema": { "type": "string" }, "example": "993267890" } ], "responses": { "200": { "description": "Collection deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CollectionNotFount": { "value": { "error": "collection not found" } }, "NewResourceCollectionNotFount": { "value": { "error": "the new resource collection is not found" } } } } } } } } }, "/hub/nodes": { "post": { "tags": [ "Nodes" ], "summary": "Create a new node", "description": "Creates a new node template within a collection", "operationId": "createNode", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNodeRequest" }, "examples": { "FunctionNode": { "summary": "Create a function node", "value": { "collection": "ms.hub.config.collection.node.805092869", "data": { "name": "ProcessPayment", "description": "Processes a payment transaction via Stripe", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}", "currency": "{{trigger.currency}}", "customer_id": "{{trigger.customer_id}}" }, "options": { "timeout": 30000, "attempts": 3, "backoff_ms": 1000 } } } }, "MapNode": { "summary": "Create a map/transformation node", "value": { "collection": "ms.hub.config.collection.node.1025086208", "data": { "name": "TransformOrderData", "description": "Transforms order data for downstream processing", "node_type": "map", "payload": { "order_id": "{{trigger.id}}", "total_amount": "{{trigger.items | sum('price')}}", "customer": { "email": "{{trigger.customer.email}}", "name": "{{trigger.customer.full_name}}" } } } } }, "ConditionNode": { "summary": "Create a condition/branching node", "value": { "collection": "ms.hub.config.collection.node.805092869", "data": { "name": "CheckOrderAmount", "description": "Routes high-value orders to priority processing", "node_type": "condition", "payload": { "condition": "{{trigger.total > 1000}}", "true_branch": "priority_handler", "false_branch": "standard_handler" } } } }, "EvalNode": { "summary": "Create an eval node for calculations", "value": { "collection": "ms.hub.config.collection.node.1025086208", "data": { "name": "CalculateDiscount", "description": "Calculates discount based on order value", "node_type": "eval", "payload": { "code": "const total = trigger.total; return total > 500 ? total * 0.1 : total * 0.05;" } } } }, "FlowNode": { "summary": "Create a flow invocation node", "value": { "collection": "ms.hub.config.collection.node.805092869", "data": { "name": "SendNotification", "description": "Invokes the notification workflow", "node_type": "flow", "subject": "ms.hub.config.workflow.1508781670.notification-flow", "payload": { "recipient": "{{trigger.customer.email}}", "template": "order_confirmation", "data": "{{trigger}}" }, "await": false } } }, "IntegrationNode": { "summary": "Create an integration node", "value": { "collection": "ms.hub.config.collection.node.805092869", "data": { "name": "SlackNotify", "description": "Sends notification to Slack channel", "node_type": "integration", "subject": "integration.slack.post-message", "payload": { "channel": "#orders", "message": "New order received: {{trigger.order_id}}" } } } } } } } }, "responses": { "201": { "description": "Node created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNodeResponse" }, "examples": { "FunctionNodeCreated": { "summary": "Function node created", "value": { "subject": "ms.hub.config.node.805092869.98765432", "collection": "ms.hub.config.collection.node.805092869", "data": { "id": "98765432", "name": "ProcessPayment", "description": "Processes a payment transaction via Stripe", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}", "currency": "{{trigger.currency}}", "customer_id": "{{trigger.customer_id}}" }, "options": { "timeout": 30000, "attempts": 3, "backoff_ms": 1000 } }, "type": "created", "modified": 1748533179 } }, "MapNodeCreated": { "summary": "Map node created", "value": { "subject": "ms.hub.config.node.1025086208.12345678", "collection": "ms.hub.config.collection.node.1025086208", "data": { "id": "12345678", "name": "TransformOrderData", "description": "Transforms order data for downstream processing", "node_type": "map", "payload": { "order_id": "{{trigger.id}}", "total_amount": "{{trigger.items | sum('price')}}" } }, "type": "created", "modified": 1748533200 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NameRequired": { "value": { "error": "data.name is required" } }, "CollectionRequired": { "value": { "error": "a collection subject is required" } }, "InvalidCollection": { "value": { "error": "invalid collection subject" } }, "PayloadRequired": { "value": { "error": "payload is required" } }, "FunctionSubjectRequired": { "value": { "error": "a function subject is required" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CollectionNotFound": { "value": { "error": "collection not found" } }, "FunctionNotFound": { "value": { "error": "function not found" } } } } } }, "409": { "description": "Node already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "node exists:ms.hub.config.node.1234567890.98765432" } } } } } }, "get": { "tags": [ "Nodes" ], "summary": "List node templates", "description": "Retrieves a list of node templates, optionally filtered by collection and type", "operationId": "listNodeTemplates", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/collectionTopic" } ], "responses": { "200": { "description": "Nodes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNodesResponse" }, "examples": { "AllNodes": { "summary": "List all nodes", "value": { "results_total": 3, "results": [ { "subject": "ms.hub.config.node.805092869.98765432", "collection": "ms.hub.config.collection.node.805092869", "data": { "id": "98765432", "name": "ProcessPayment", "description": "Processes payment via Stripe", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}" } }, "type": "created", "modified": 1748533179 }, { "subject": "ms.hub.config.node.805092869.11223344", "collection": "ms.hub.config.collection.node.805092869", "data": { "id": "11223344", "name": "ValidateCard", "node_type": "function", "subject": "quiva-function.card-validator", "payload": { "card_number": "{{trigger.card}}" } }, "type": "updated", "modified": 1748533200 }, { "subject": "ms.hub.config.node.1025086208.55667788", "collection": "ms.hub.config.collection.node.1025086208", "data": { "id": "55667788", "name": "TransformData", "node_type": "map", "payload": { "output": "{{trigger.input | uppercase}}" } }, "type": "created", "modified": 1748533250 } ] } }, "FilteredByCollection": { "summary": "Nodes filtered by collection", "value": { "results_total": 2, "results": [ { "subject": "ms.hub.config.node.805092869.98765432", "collection": "ms.hub.config.collection.node.805092869", "data": { "id": "98765432", "name": "ProcessPayment", "node_type": "function", "subject": "quiva-function.stripe-charge" }, "type": "created", "modified": 1748533179 }, { "subject": "ms.hub.config.node.805092869.11223344", "collection": "ms.hub.config.collection.node.805092869", "data": { "id": "11223344", "name": "ValidateCard", "node_type": "function", "subject": "quiva-function.card-validator" }, "type": "updated", "modified": 1748533200 } ] } }, "EmptyResult": { "summary": "No nodes found", "value": { "results_total": 0, "results": [] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "invalid request" } } } } } } }, "/hub/nodes/{collection_topic}/{node_topic}": { "parameters": [ { "$ref": "#/components/parameters/collectionTopic" }, { "$ref": "#/components/parameters/nodeTopic" } ], "get": { "tags": [ "Nodes" ], "summary": "Get a node", "description": "Retrieves a specific node by subject", "operationId": "getNode", "x-resource-type": "service", "responses": { "200": { "description": "Node retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNodeResponse" }, "examples": { "FunctionNode": { "summary": "Retrieved function node", "value": { "subject": "ms.hub.config.node.805092869.98765432", "data": { "id": "98765432", "name": "ProcessPayment", "description": "Processes a payment transaction via Stripe", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}", "currency": "{{trigger.currency}}", "customer_id": "{{trigger.customer_id}}" }, "options": { "timeout": 30000, "attempts": 3, "backoff_ms": 1000, "ignore_response_codes": [ 404, 429 ] } }, "modified": 1748533179 } }, "MapNode": { "summary": "Retrieved map node", "value": { "subject": "ms.hub.config.node.1025086208.55667788", "data": { "id": "55667788", "name": "TransformOrderData", "description": "Transforms order data structure", "node_type": "map", "payload": { "order_id": "{{trigger.id}}", "total": "{{trigger.items | sum('price')}}", "customer_email": "{{trigger.customer.email}}" }, "response_map": { "processed_order": "{{result}}" } }, "modified": 1748533200 } }, "ConditionNode": { "summary": "Retrieved condition node", "value": { "subject": "ms.hub.config.node.805092869.33445566", "data": { "id": "33445566", "name": "CheckOrderValue", "description": "Routes orders based on value threshold", "node_type": "condition", "payload": { "condition": "{{trigger.total > 1000}}" } }, "modified": 1748533250 } }, "FlowNode": { "summary": "Retrieved flow invocation node", "value": { "subject": "ms.hub.config.node.805092869.77889900", "data": { "id": "77889900", "name": "TriggerNotificationFlow", "description": "Invokes notification workflow asynchronously", "node_type": "flow", "subject": "ms.hub.config.workflow.1508781670.notify", "payload": { "recipient": "{{trigger.email}}", "message": "{{trigger.message}}" }, "await": false, "options": { "timeout": 60000 } }, "modified": 1748533300 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } }, "patch": { "tags": [ "Nodes" ], "summary": "Update a node", "description": "Updates an existing node's properties", "operationId": "updateNode", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNodeRequest" }, "examples": { "UpdatePayload": { "summary": "Update node payload", "value": { "subject": "ms.hub.config.node.805092869.98765432", "data": { "name": "ProcessPayment", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}", "currency": "{{trigger.currency}}", "customer_id": "{{trigger.customer_id}}", "metadata": { "order_id": "{{trigger.order_id}}" } } } } }, "UpdateOptions": { "summary": "Update node options", "value": { "subject": "ms.hub.config.node.805092869.98765432", "data": { "name": "ProcessPayment", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}" }, "options": { "timeout": 60000, "attempts": 5, "backoff_ms": 2000, "ignore_response_codes": [ 404, 429, 503 ] } } } }, "UpdateDescription": { "summary": "Update node description", "value": { "subject": "ms.hub.config.node.1025086208.55667788", "data": { "name": "TransformOrderData", "description": "Updated: Transforms and enriches order data for analytics", "node_type": "map", "payload": { "order_id": "{{trigger.id}}" } } } }, "ArchiveNode": { "summary": "Archive a node", "value": { "subject": "ms.hub.config.node.805092869.11223344", "data": { "name": "DeprecatedValidator", "node_type": "function", "subject": "quiva-function.old-validator" }, "archived": true } } } } } }, "responses": { "200": { "description": "Node updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SubjectRequired": { "value": { "error": "a subject is required" } }, "FunctionNotFound": { "value": { "error": "function not found" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FlowNotFound": { "value": { "error": "flow not found" } } } } } } } }, "delete": { "tags": [ "Nodes" ], "summary": "Delete a node", "description": "Deletes a specific node by subject", "operationId": "deleteNode", "x-resource-type": "service", "responses": { "200": { "description": "Node deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } } }, "/hub/nodes/batch": { "patch": { "tags": [ "Nodes" ], "summary": "Update multiple nodes", "description": "Updates multiple existing nodes in a single request", "operationId": "updateMultipleNodes", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMultiNodeRequest" }, "examples": { "UpdateMultipleFunctionNodes": { "summary": "Update multiple function nodes", "value": [ { "subject": "ms.hub.config.node.805092869.98765432", "data": { "name": "ProcessPaymentV2", "node_type": "function", "subject": "quiva-function.stripe-charge-v2", "payload": { "amount": "{{trigger.amount}}", "currency": "{{trigger.currency}}" }, "options": { "timeout": 45000 } } }, { "subject": "ms.hub.config.node.805092869.11223344", "data": { "name": "ValidateCardV2", "node_type": "function", "subject": "quiva-function.card-validator-v2", "payload": { "card_number": "{{trigger.card}}", "cvv": "{{trigger.cvv}}" } } } ] }, "UpdateMixedNodeTypes": { "summary": "Update nodes of different types", "value": [ { "subject": "ms.hub.config.node.805092869.98765432", "data": { "name": "ProcessPayment", "node_type": "function", "subject": "quiva-function.stripe-charge", "payload": { "amount": "{{trigger.amount}}" } } }, { "subject": "ms.hub.config.node.1025086208.55667788", "data": { "name": "TransformOrder", "node_type": "map", "payload": { "order_id": "{{trigger.id}}", "status": "processed" } } }, { "subject": "ms.hub.config.node.805092869.33445566", "data": { "name": "CheckThreshold", "node_type": "condition", "payload": { "condition": "{{trigger.total > 500}}" } } } ] }, "ArchiveMultipleNodes": { "summary": "Archive multiple deprecated nodes", "value": [ { "subject": "ms.hub.config.node.805092869.oldnode1", "data": { "name": "DeprecatedNode1", "node_type": "function", "subject": "quiva-function.old-function" }, "archived": true }, { "subject": "ms.hub.config.node.805092869.oldnode2", "data": { "name": "DeprecatedNode2", "node_type": "map", "payload": {} }, "archived": true } ] } } } } }, "responses": { "200": { "description": "All nodes updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMultiNodeResponse" }, "examples": { "AllSuccess": { "summary": "All nodes updated successfully", "value": [ { "node": { "subject": "ms.hub.config.node.805092869.98765432", "data": { "name": "ProcessPaymentV2", "node_type": "function", "subject": "quiva-function.stripe-charge-v2", "payload": { "amount": "{{trigger.amount}}" } } }, "result": "success" }, { "node": { "subject": "ms.hub.config.node.805092869.11223344", "data": { "name": "ValidateCardV2", "node_type": "function", "subject": "quiva-function.card-validator-v2", "payload": { "card_number": "{{trigger.card}}" } } }, "result": "success" } ] } } } } }, "400": { "description": "Some nodes failed to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMultiNodeErrorResponse" }, "example": { "body": [ { "node": { "subject": "ms.hub.config.node.1234567890.98765432", "data": { "name": "UpdatedNode1", "node_type": "function", "subject": "quiva-function.function1", "payload": { "param1": "value1" } } }, "result": "succes" }, { "node": { "subject": "ms.hub.config.node.1234567890.12345678", "data": { "name": "UpdatedNode2", "node_type": "function", "subject": "quiva-function.non-existing-function", "payload": { "param2": "value2" } } }, "result": "error: function not found" } ], "error": "some nodes failed to upsert" } } } } } } }, "/hub/workflows": { "post": { "tags": [ "Workflows" ], "summary": "Create a new workflow", "description": "Creates a draft workflow in a collection. Publish it to make it executable. Server-side validation (validate=true) checks duplicate/reserved/invalid node ids, missing payloads, and edges referencing missing nodes or functions/flows that do not exist. It does not check for cycles.", "operationId": "createWorkflow", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" }, "examples": { "simpleWorkflow": { "summary": "Simple two-node workflow", "value": { "name": "MyWorkflow", "collection": "ms.hub.config.collection.workflow.1234567890", "description": "A workflow that processes data", "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Start of workflow" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process-function", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "edge1" } ], "result": "process" } } }, "conditionalWorkflow": { "summary": "Workflow with conditional branching", "value": { "name": "ConditionalProcessing", "collection": "ms.hub.config.collection.workflow.9876543210", "description": "A workflow with conditional logic", "config": { "nodes": [ { "data": { "id": "input", "name": "Input Handler", "node_type": "map", "payload": { "data": "{trigger.body}" } } }, { "data": { "id": "check_type", "name": "Check Type", "node_type": "condition", "payload": { "condition": "{input.type} == 'premium'" } } }, { "data": { "id": "premium_handler", "name": "Premium Handler", "node_type": "function", "subject": "quiva-function.premium-processor", "payload": { "input": "{input}" } } }, { "data": { "id": "standard_handler", "name": "Standard Handler", "node_type": "function", "subject": "quiva-function.standard-processor", "payload": { "input": "{input}" } } } ], "edges": [ { "source": "input", "target": "check_type", "id": "e1" }, { "source": "check_type", "target": "premium_handler", "id": "e2", "sourceHandle": "true" }, { "source": "check_type", "target": "standard_handler", "id": "e3", "sourceHandle": "false" } ], "result": "{check_type} ? {premium_handler} : {standard_handler}" } } }, "debouncedWorkflow": { "summary": "Workflow with debouncing", "value": { "name": "DebouncedNotifications", "collection": "ms.hub.config.collection.workflow.5555555555", "description": "Debounces rapid notifications by user", "config": { "nodes": [ { "data": { "id": "aggregate", "name": "Aggregate Events", "node_type": "map", "payload": { "user_id": "{trigger.user_id}", "events": "{trigger.events}" } } }, { "data": { "id": "send_notification", "name": "Send Notification", "node_type": "function", "subject": "quiva-function.send-email", "payload": { "to": "{aggregate.user_id}", "body": "{aggregate.events}" } } } ], "edges": [ { "source": "aggregate", "target": "send_notification", "id": "e1" } ], "result": "send_notification", "options": { "run_type": "debounced", "debounce_on": "{trigger.user_id}", "debounce_time": 5000, "debounce_max": 30000 } } } }, "evalWorkflow": { "summary": "Workflow using eval node for calculations", "value": { "name": "PriceCalculator", "collection": "ms.hub.config.collection.workflow.7777777777", "description": "Calculates pricing with discounts", "config": { "nodes": [ { "data": { "id": "get_prices", "name": "Get Base Prices", "node_type": "function", "subject": "quiva-function.get-pricing", "payload": { "product_ids": "{trigger.products}" } } }, { "data": { "id": "calculate_total", "name": "Calculate Total", "node_type": "eval", "payload": { "code": "const prices = get_prices.items; const subtotal = prices.reduce((sum, p) => sum + p.price * p.quantity, 0); const discount = trigger.discount_percent || 0; return { subtotal, discount: subtotal * discount / 100, total: subtotal * (1 - discount / 100) };" } } } ], "edges": [ { "source": "get_prices", "target": "calculate_total", "id": "e1" } ], "result": "calculate_total" } } }, "nestedFlowWorkflow": { "summary": "Workflow calling another flow", "value": { "name": "OrderProcessor", "collection": "ms.hub.config.collection.workflow.8888888888", "description": "Processes orders by calling sub-workflows", "config": { "nodes": [ { "data": { "id": "validate", "name": "Validate Order", "node_type": "function", "subject": "quiva-function.validate-order", "payload": { "order": "{trigger.order}" } } }, { "data": { "id": "process_payment", "name": "Process Payment", "node_type": "flow", "subject": "ms.hub.config.workflow.8888888888.payment-flow", "await": true, "payload": { "amount": "{validate.total}", "customer_id": "{trigger.customer_id}" } } }, { "data": { "id": "fulfill", "name": "Fulfill Order", "node_type": "flow", "subject": "ms.hub.config.workflow.8888888888.fulfillment-flow", "await": false, "payload": { "order_id": "{validate.order_id}", "payment_ref": "{process_payment.reference}" } } } ], "edges": [ { "source": "validate", "target": "process_payment", "id": "e1" }, { "source": "process_payment", "target": "fulfill", "id": "e2" } ], "result": "fulfill" } } }, "integrationWorkflow": { "summary": "Workflow with external integration", "value": { "name": "SlackNotifier", "collection": "ms.hub.config.collection.workflow.3333333333", "description": "Sends notifications to Slack", "config": { "nodes": [ { "data": { "id": "format_message", "name": "Format Message", "node_type": "map", "payload": { "channel": "#alerts", "text": "Alert: {trigger.message}", "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": "*{trigger.title}*\n{trigger.message}" } } ] } } }, { "data": { "id": "send_slack", "name": "Send to Slack", "node_type": "integration", "subject": "slack.chat.postMessage", "payload": "{format_message}", "options": { "timeout": 10000, "attempts": 3, "backoff_ms": 1000 } } } ], "edges": [ { "source": "format_message", "target": "send_slack", "id": "e1" } ], "result": "send_slack" } } } } } } }, "responses": { "201": { "description": "Workflow created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowResponse" }, "examples": { "simpleWorkflowCreated": { "summary": "Simple workflow created", "value": { "subject": "ms.hub.config.workflow.draft.1234567890.98765432", "name": "MyWorkflow", "collection": "ms.hub.config.collection.workflow.1234567890", "description": "A workflow that processes data", "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Start of workflow" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process-function", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "edge1" } ], "result": "process" }, "modified": 1651395678 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NameRequired": { "value": { "error": "a name is required" } }, "CollectionRequired": { "value": { "error": "a collection subject is required" } }, "InvalidCollection": { "value": { "error": "invalid collection subject" } }, "InvalidNodeId": { "value": { "error": "invalid ID. An ID must start with a letter or underscore and must contain only alphanumeric characters, hyphens and underscores" } }, "ReservedWord": { "value": { "error": "cannot use a reserved word as a node id:trigger" } }, "PayloadRequired": { "value": { "error": "payload is required:nodeId" } }, "FunctionSubjectRequired": { "value": { "error": "a subject is required for the function:nodeId" } }, "FlowSubjectRequired": { "value": { "error": "a subject is required for the flow:nodeId" } }, "DuplicateNodeId": { "value": { "error": "duplicate node id found:nodeId" } }, "EdgeSourceTargetRequired": { "value": { "error": "source and target required on edge: source->target" } }, "SourceNodeNotFound": { "value": { "error": "source node not found:source->target" } }, "TargetNodeNotFound": { "value": { "error": "target node not found:source->target" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CollectionNotFound": { "value": { "error": "collection not found" } }, "FunctionNotFound": { "value": { "error": "function not found" } } } } } }, "409": { "description": "Workflow already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "workflow exists:ms.hub.config.workflow.draft.1234567890.98765432" } } } } } }, "get": { "tags": [ "Workflows" ], "summary": "List workflows", "description": "Retrieves a list of workflows, optionally filtered by collection and type", "operationId": "listWorkflows", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/collectionTopic" }, { "name": "filter", "in": "query", "description": "Filter workflows by type. If not specified, all types will be listed", "required": false, "schema": { "type": "string", "enum": [ "draft", "published" ] }, "examples": { "draft": { "summary": "List only draft workflows", "value": "draft" }, "published": { "summary": "List only published workflows", "value": "published" } } } ], "responses": { "200": { "description": "Workflows retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowsResponse" }, "examples": { "multipleWorkflows": { "summary": "Multiple workflows returned", "value": { "results": [ { "subject": "ms.hub.config.workflow.draft.1234567890.98765432", "name": "DataProcessor", "description": "Processes incoming data", "config": { "nodes": [ { "data": { "id": "input", "name": "Input", "node_type": "map", "payload": { "data": "{trigger}" } } } ], "edges": [], "result": "input" }, "modified": 1651395678 }, { "subject": "ms.hub.config.workflow.draft.1234567890.12345678", "name": "NotificationSender", "description": "Sends notifications to users", "config": { "nodes": [ { "data": { "id": "send", "name": "Send", "node_type": "function", "subject": "quiva-function.send-email", "payload": { "to": "{trigger.email}" } } } ], "edges": [], "result": "send" }, "modified": 1651395679 } ], "results_total": 2 } }, "emptyList": { "summary": "No workflows found", "value": { "results": [], "results_total": 0 } }, "singleWorkflow": { "summary": "Single workflow returned", "value": { "results": [ { "subject": "ms.hub.config.workflow.1234567890.11111111", "name": "ProductionWorkflow", "description": "Published production workflow", "config": { "nodes": [ { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.processor", "payload": {} } } ], "edges": [], "result": "process" }, "modified": 1651400000 } ], "results_total": 1 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "invalid request" } } } } } } }, "/hub/workflows/{collection_topic}/{flow_topic}": { "parameters": [ { "$ref": "#/components/parameters/collectionTopic" }, { "$ref": "#/components/parameters/flowTopic" } ], "get": { "tags": [ "Workflows" ], "summary": "Get a workflow", "description": "Fetch a workflow’s full config (nodes, edges, static, result). Path segments are the last two parts of the workflow subject.", "operationId": "getWorkflow", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/queryDraftFlag" } ], "responses": { "200": { "description": "Workflow retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowResponse" }, "examples": { "simpleWorkflow": { "summary": "Simple workflow with map and function nodes", "value": { "subject": "ms.hub.config.workflow.1234567890.98765432", "name": "MyWorkflow", "description": "Workflow description", "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Start of workflow" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process-function", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "edge1" } ], "result": "process" }, "modified": 1651395678 } }, "draftWorkflow": { "summary": "Draft workflow with static data", "value": { "subject": "ms.hub.config.workflow.draft.1234567890.55555555", "name": "DraftWorkflow", "description": "Work in progress workflow", "config": { "nodes": [ { "data": { "id": "init", "name": "Initialize", "node_type": "map", "payload": { "config": "{static.defaultConfig}", "input": "{trigger}" } } } ], "edges": [], "static": { "defaultConfig": { "timeout": 30000, "retries": 3 } }, "result": "init" }, "modified": 1651400000 } }, "complexWorkflow": { "summary": "Complex workflow with multiple node types", "value": { "subject": "ms.hub.config.workflow.1234567890.77777777", "name": "OrderProcessingWorkflow", "description": "Complete order processing pipeline", "config": { "nodes": [ { "data": { "id": "validate_input", "name": "Validate Input", "node_type": "function", "subject": "quiva-function.validate-order", "payload": { "order": "{trigger.order}" }, "options": { "timeout": 5000 } } }, { "data": { "id": "check_inventory", "name": "Check Inventory", "node_type": "function", "subject": "quiva-function.check-stock", "payload": { "items": "{validate_input.items}" } } }, { "data": { "id": "has_stock", "name": "Has Stock?", "node_type": "condition", "payload": { "condition": "{check_inventory.available} == true" } } }, { "data": { "id": "process_order", "name": "Process Order", "node_type": "flow", "subject": "ms.hub.config.workflow.1234567890.order-processor", "await": true, "payload": { "order": "{validate_input}" } } }, { "data": { "id": "backorder", "name": "Create Backorder", "node_type": "function", "subject": "quiva-function.create-backorder", "payload": { "order": "{validate_input}" } } }, { "data": { "id": "notify_customer", "name": "Notify Customer", "node_type": "integration", "subject": "email.send", "payload": { "to": "{trigger.customer_email}", "template": "order_confirmation", "data": "{process_order}" } } } ], "edges": [ { "source": "validate_input", "target": "check_inventory", "id": "e1" }, { "source": "check_inventory", "target": "has_stock", "id": "e2" }, { "source": "has_stock", "target": "process_order", "id": "e3", "sourceHandle": "true" }, { "source": "has_stock", "target": "backorder", "id": "e4", "sourceHandle": "false" }, { "source": "process_order", "target": "notify_customer", "id": "e5" } ], "result": "{has_stock} ? {notify_customer} : {backorder}" }, "modified": 1651450000 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } }, "patch": { "tags": [ "Workflows" ], "summary": "Update a workflow", "description": "Partial update — only the fields you provide change. Updating a published workflow creates a new draft; publish again to make the changes live.", "operationId": "updateWorkflow", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowRequest" }, "examples": { "updateNameAndDescription": { "summary": "Update name and description only", "value": { "name": "UpdatedWorkflowName", "description": "Updated workflow description" } }, "updateConfig": { "summary": "Update workflow configuration", "value": { "name": "UpdatedWorkflow", "description": "Updated workflow description", "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Updated start of workflow" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.updated-process-function", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "edge1" } ], "result": "process" } } }, "addNode": { "summary": "Add a new node to existing workflow", "value": { "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Start" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process", "payload": { "input": "{start}" } } }, { "data": { "id": "notify", "name": "Notify", "node_type": "integration", "subject": "slack.chat.postMessage", "payload": { "channel": "#alerts", "text": "Processed: {process.result}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "e1" }, { "source": "process", "target": "notify", "id": "e2" } ], "result": "notify" } } }, "archiveWorkflow": { "summary": "Archive a workflow", "value": { "archived": true } } } } } }, "responses": { "200": { "description": "Workflow updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowResponse" }, "examples": { "updated": { "summary": "Workflow updated successfully", "value": { "subject": "ms.hub.config.workflow.draft.1234567890.98765432", "name": "UpdatedWorkflow", "description": "Updated workflow description", "config": { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Updated start of workflow" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.updated-process-function", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "edge1" } ], "result": "process" }, "modified": 1651395678 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SubjectRequired": { "value": { "error": "subject is required" } }, "InvalidDraftSubject": { "value": { "error": "a valid draft subject is required" } } } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "workflow not found" } } } } } }, "delete": { "tags": [ "Workflows" ], "summary": "Delete a workflow", "description": "Deletes a specific workflow by subject", "operationId": "deleteWorkflow", "x-resource-type": "service", "responses": { "200": { "description": "Workflow deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "invalid subject" } } } } } } } } }, "/hub/workflows/{collection_topic}/{flow_topic}/run": { "parameters": [ { "$ref": "#/components/parameters/collectionTopic" }, { "$ref": "#/components/parameters/flowTopic" }, { "$ref": "#/components/parameters/queryDraftFlag" } ], "post": { "tags": [ "Workflows" ], "summary": "Run a workflow", "description": "Executes a workflow with the specified trigger data\n\nResuming a run that is not paused or errored answers 409; it does not start the flow again. The paused entry is claimed when the resume is accepted, so a second submit is refused. A call with `await: false` can now return an error, including start-up failures, and waits for the first stream write.", "operationId": "runWorkflow", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowRequest" }, "examples": { "singleTriggerSync": { "summary": "Single trigger with synchronous execution", "value": { "trigger": { "user_id": "user_123", "action": "process_order", "data": { "order_id": "ORD-456", "items": [ { "sku": "PROD-001", "quantity": 2 }, { "sku": "PROD-002", "quantity": 1 } ], "total": 149.99 } }, "enable_log": true, "await": true } }, "singleTriggerAsync": { "summary": "Single trigger with asynchronous execution", "value": { "trigger": { "event_type": "webhook", "payload": { "source": "external_system", "data": { "key": "value" } } }, "enable_log": false, "await": false } }, "multipleTriggers": { "summary": "Multiple triggers for batch processing", "value": { "triggers": [ { "user_id": "user_001", "email": "user1@example.com", "notification_type": "welcome" }, { "user_id": "user_002", "email": "user2@example.com", "notification_type": "welcome" }, { "user_id": "user_003", "email": "user3@example.com", "notification_type": "welcome" } ], "enable_log": true, "await": false } }, "minimalTrigger": { "summary": "Minimal trigger with just data", "value": { "trigger": { "message": "Hello, World!" } } }, "complexTrigger": { "summary": "Complex trigger with nested data", "value": { "trigger": { "timestamp": 1651395678, "source": "api", "customer": { "id": "cust_789", "name": "John Doe", "email": "john@example.com", "tier": "premium" }, "order": { "id": "ORD-12345", "items": [ { "product_id": "P001", "name": "Widget", "quantity": 5, "unit_price": 19.99 }, { "product_id": "P002", "name": "Gadget", "quantity": 2, "unit_price": 49.99 } ], "shipping": { "method": "express", "address": { "street": "123 Main St", "city": "Springfield", "country": "US" } } }, "metadata": { "utm_source": "google", "campaign_id": "summer_sale" } }, "enable_log": true, "await": true } } } } } }, "responses": { "200": { "description": "Workflow executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowResponse" }, "examples": { "awaitedSuccess": { "summary": "Synchronous execution completed", "value": { "trackingId": "ms.hub.run.abcdef-1234-5678-90ab-cdef12345678.ms.hub.config.workflow.1234567890.98765432", "result": { "status": "completed", "order_id": "ORD-456", "processed_at": "2024-01-15T10:30:00Z", "confirmation_number": "CONF-789012" } } }, "notAwaitedSuccess": { "summary": "Asynchronous execution started", "value": { "trackingId": "ms.hub.run.fedcba-9876-5432-10ab-cdef98765432.ms.hub.config.workflow.1234567890.98765432" } }, "debouncedRun": { "summary": "Debounced execution", "value": { "body": "debounced run: user_123-notifications" } }, "orderedRun": { "summary": "Ordered execution queued", "value": "ordered run: order_queue-ORD-456" }, "complexResult": { "summary": "Complex workflow result", "value": { "trackingId": "ms.hub.run.12345678-abcd-efgh-ijkl-mnopqrstuvwx.ms.hub.config.workflow.9876543210.11111111", "result": { "validation": { "status": "passed", "checks": [ "inventory", "payment", "fraud" ] }, "processing": { "order_id": "ORD-12345", "payment_id": "PAY-67890", "fulfillment_id": "FUL-11111" }, "notifications_sent": [ { "type": "email", "status": "sent" }, { "type": "sms", "status": "sent" } ], "metadata": { "duration_ms": 1523, "nodes_executed": 7 } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NoTrigger": { "value": { "error": "no trigger specified" } }, "ArchivedFlow": { "value": { "error": "cannot run an archived flow" } }, "MissingConfig": { "value": { "error": "missing configuration" } }, "NodesRequired": { "value": { "error": "nodes are required" } }, "DebounceError": { "value": { "error": "failed to resolve debounceOn" } }, "OrderOnError": { "value": { "error": "failed to resolve orderOn" } } } } } }, "409": { "description": "The run is not paused or errored, or there is no errors entry to retry. A second resume of the same pause is refused the same way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/workflows/{collection_topic}/{flow_topic}/history": { "parameters": [ { "$ref": "#/components/parameters/collectionTopic" }, { "$ref": "#/components/parameters/flowTopic" }, { "$ref": "#/components/parameters/queryDraftFlag" } ], "get": { "tags": [ "Workflows" ], "summary": "Workflow Configuration History", "description": "Get workflow configuration history", "operationId": "workflowHistory", "x-resource-type": "service", "responses": { "200": { "description": "Workflow history", "content": { "application/json": { "schema": { "type": "array", "description": "An array of full configuration versions", "items": { "$ref": "#/components/schemas/WorkflowConfig" } }, "examples": { "multipleVersions": { "summary": "Multiple configuration versions", "value": [ { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Version 3 - Current" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process-v3", "payload": { "input": "{start}" } } }, { "data": { "id": "notify", "name": "Notify", "node_type": "integration", "subject": "slack.chat.postMessage", "payload": { "channel": "#alerts", "text": "{process.result}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "e1" }, { "source": "process", "target": "notify", "id": "e2" } ], "result": "notify" }, { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Version 2" } } }, { "data": { "id": "process", "name": "Process", "node_type": "function", "subject": "quiva-function.process-v2", "payload": { "input": "{start}" } } } ], "edges": [ { "source": "start", "target": "process", "id": "e1" } ], "result": "process" }, { "nodes": [ { "data": { "id": "start", "name": "Start", "node_type": "map", "payload": { "message": "Version 1 - Initial" } } } ], "edges": [], "result": "start" } ] }, "singleVersion": { "summary": "Single version (new workflow)", "value": [ { "nodes": [ { "data": { "id": "init", "name": "Initialize", "node_type": "map", "payload": { "status": "ready" } } } ], "edges": [], "result": "init" } ] }, "emptyHistory": { "summary": "No history available", "value": [] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NoTrigger": { "value": { "error": "no trigger specified" } }, "ArchivedFlow": { "value": { "error": "cannot run an archived flow" } }, "MissingConfig": { "value": { "error": "missing configuration" } }, "NodesRequired": { "value": { "error": "nodes are required" } }, "DebounceError": { "value": { "error": "failed to resolve debounceOn" } }, "OrderOnError": { "value": { "error": "failed to resolve orderOn" } } } } } } } } }, "/hub/workflows/publish": { "post": { "tags": [ "Workflows" ], "summary": "Publish a workflow", "description": "Makes the workflow executable and wires up any schedule triggers.", "operationId": "publishWorkflow", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishWorkflowRequest" }, "example": { "subject": "ms.hub.config.workflow.draft.1234567890.98765432" } } } }, "responses": { "200": { "description": "Workflow published successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "success" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InvalidSubject": { "value": { "error": "a valid draft subject is required" } } } } } } } } }, "/hub/integrations/oauth-config": { "get": { "summary": "List OAuth configurations", "description": "Get list of all OAuth configurations", "operationId": "getIntegrationsOauthConfigs", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "List of OAuth configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConfigList" }, "example": { "results": [ { "integration_id": "slack", "name": "Slack API", "scopes": "channels:read,chat:write,users:read", "subject": "ms.integration.oauth.config.slack" }, { "integration_id": "xero", "name": "Xero API's", "scopes": "email,openid,profile,assets,assets.read,files,files.read,projects,projects.read", "subject": "ms.integration.oauth.config.xero" }, { "integration_id": "google", "name": "Google Workspace", "scopes": "https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar", "subject": "ms.integration.oauth.config.google" } ], "results_total": 3 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/{integration_id}/oauth-config": { "parameters": [ { "$ref": "#/components/parameters/integrationId" } ], "get": { "summary": "Get OAuth configuration", "description": "Get OAuth configuration for a specific integration", "operationId": "getIntegrationOauthConfig", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "OAuth configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConfigBasicData" }, "examples": { "slack": { "summary": "Slack OAuth config", "value": { "integration_id": "slack", "name": "Slack API", "scopes": "channels:read,chat:write,users:read", "subject": "ms.integration.oauth.config.slack" } }, "xero": { "summary": "Xero OAuth config", "value": { "integration_id": "xero", "name": "Xero API's", "scopes": "email,openid,profile,assets,assets.read", "subject": "ms.integration.oauth.config.xero" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an OAuth configuration.", "description": "[quiva.ai admins only] Update the OAuth configuration for a specific integration - full configuration replacement", "operationId": "putIntegrationsOauthConfig", "tags": [ "Oauth" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOauthConfig" }, "examples": { "slack": { "summary": "Slack OAuth configuration", "value": { "integration_id": "slack", "name": "Slack API", "scopes": "channels:read,chat:write,users:read,files:read", "client_id": "123456789.987654321", "client_secret": "abcdef1234567890abcdef", "auth_url": "https://slack.com/oauth/v2/authorize", "token_url": "https://slack.com/api/oauth.v2.access", "redirect_url": "https://api.quiva.ai/hub/integrations/oauth-callback" } }, "github": { "summary": "GitHub OAuth configuration", "value": { "integration_id": "github", "name": "GitHub API", "scopes": "repo,read:user,read:org", "client_id": "Iv1.a1b2c3d4e5f6g7h8", "client_secret": "secret123456789abcdef", "auth_url": "https://github.com/login/oauth/authorize", "token_url": "https://github.com/login/oauth/access_token", "redirect_url": "https://api.quiva.ai/hub/integrations/oauth-callback" } } } } } }, "responses": { "200": { "description": "OAuth configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an OAuth configuration.", "description": "[quiva.ai admins only] Deletes an OAuth configuration for a specific integration", "operationId": "deleteIntegrationsOauthConfig", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "OAuth configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/oauth-connections": { "get": { "summary": "List OAuth connections", "description": "Get list of OAuth connections for the authenticated user", "operationId": "getIntegrationsOauthConnections", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "List of OAuth connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConnectionsList" }, "example": { "results": [ { "access_token": "eyJhbGciOiJSUzI1Ni...", "token_type": "Bearer", "refresh_token": "xoxr-123456789012-refresh-token", "expiry": "2025-06-15T14:30:00.000000+00:00", "expires_in": 43200, "sequence": 42, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.slack.workspace1", "modified": 1749912600 }, { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "refresh_token": "ulpL_xero_refresh_token_abc123", "expiry": "2025-06-15T15:00:00.000000+00:00", "expires_in": 1800, "sequence": 85, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo", "modified": 1749914400 }, { "access_token": "eyJhbGciOiJSUzI1Ni...", "token_type": "Bearer", "expiry": "2025-12-31T23:59:59.000000+00:00", "expires_in": 31536000, "sequence": 12, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.github.personal", "modified": 1749900000 } ], "results_total": 3 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/{integration_id}/oauth-token/{connection_id}": { "parameters": [ { "$ref": "#/components/parameters/integrationId" }, { "$ref": "#/components/parameters/connectionId" } ], "get": { "summary": "Get OAuth connection", "description": "Get OAuth connection details for a specific integration and connection", "operationId": "getIntegrationsOauthConnection", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "OAuth connection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConnection" }, "example": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "refresh_token": "ulpL_xGHJwk9RmT2PnCq...", "expiry": "2025-05-29T17:09:39.816102+01:00", "expires_in": 1800, "sequence": 85, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo", "modified": 1748533179 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/{integration_id}/oauth-connections": { "parameters": [ { "$ref": "#/components/parameters/integrationId" } ], "get": { "summary": "Get integration connections", "description": "Gets integration connections by integration_id", "operationId": "getIntegrationConnections", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "Connection deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConnection" }, "example": { "results": [ { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "refresh_token": "ulpL_...", "expiry": "2025-05-29T17:09:39.816102+01:00", "expires_in": 1800, "sequence": 85, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo", "modified": 1748533179 }, { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "refresh_token": "pSn5h...", "expiry": "2025-05-29T17:11:54.397804+01:00", "expires_in": 1800, "sequence": 86, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.maria", "modified": 1748533314 } ], "results_total": 2 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/{integration_id}/oauth-connections/{connection_id}": { "delete": { "summary": "Delete OAuth connection", "description": "Delete an OAuth connection for a specific integration", "operationId": "deleteIntegrationsOauthConnection", "tags": [ "Oauth" ], "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/integrationId" }, { "$ref": "#/components/parameters/connectionId" } ], "responses": { "200": { "description": "Connection deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/oauth-callback": { "get": { "summary": "OAuth callback", "description": "Handle OAuth callback after user authorization", "operationId": "integrationsOauthCallback", "tags": [ "Oauth" ], "x-resource-type": "service", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "OAuth authorization code", "example": "4/0AX4XfWgq1P2fJdK8V9L3m..." }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "OAuth state parameter", "example": "abc123xyz789def456ghi" } ], "responses": { "200": { "description": "OAuth token received and saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConnection" }, "example": { "access_token": "eyJhbGciOiJSUzI1Ni...", "token_type": "Bearer", "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...", "expiry": "2025-06-01T12:00:00.000000+00:00", "expires_in": 3600, "sequence": 1, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.slack.workspace1", "modified": 1748620800 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: the caller is not the user who started the login, or is not allowed to make this connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/integrations/{integration_id}/oauth-refresh-token/{connection_id}": { "get": { "summary": "Refresh OAuth token", "description": "Refresh an OAuth access token using the refresh token", "operationId": "refreshIntegrationsOauthToken", "tags": [ "Oauth" ], "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/integrationId" }, { "$ref": "#/components/parameters/connectionId" }, { "name": "refresh_token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Refresh token", "example": "pSn5h..." } ], "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthConnection" }, "example": { "access_token": "eyJhbGciOiJSUzI1Ni...", "token_type": "Bearer", "refresh_token": "bmV3UmVmcmVzaFRva2VuVmFsdWU...", "expiry": "2025-05-30T18:00:00.000000+01:00", "expires_in": 1800, "sequence": 87, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.maria", "modified": 1748622000 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hub/workflows/run": { "post": { "summary": "Execute a workflow", "description": "Run a published workflow. await=true returns results synchronously; await=false returns a tracking_id immediately. Resume a paused (input/human-in-the-loop) run by passing its run_id plus the human response as trigger.\n\nResuming a run that is not paused or errored answers 409; it does not start the flow again. The paused entry is claimed when the resume is accepted, so a second submit is refused. A call with `await: false` can now return an error, including start-up failures, and waits for the first stream write.", "operationId": "runWorkflowBySubject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowRequest" }, "examples": { "sync": { "summary": "Synchronous run", "value": { "subject": "ms.hub.config.workflow.4285896071.1009853675", "trigger": { "description": "reverses a string" }, "await": true } }, "resumePaused": { "summary": "Resume a paused human-in-the-loop run", "value": { "subject": "ms.hub.config.workflow.4285896071.1009853675", "run_id": "ms.hub.run.uuid123.ms.hub.config.workflow.4285896071.1009853675", "trigger": { "approved": true }, "await": true } } } } } }, "responses": { "200": { "description": "Run result. { tracking_id, result }. If config.result was set, result matches that JSONPath selection; otherwise result is the step-by-step log array where items with a 'paused': true flag indicate a human-in-the-loop pause (resume with run_id).", "content": { "application/json": { "example": { "tracking_id": "ms.hub.run.abc123.ms.hub.config.workflow.4285896071.1009853675", "result": "export function reverse(s){return [...s].reverse().join('')}" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Workflow not found or not published" }, "409": { "description": "The run is not paused or errored, or there is no errors entry to retry. A second resume of the same pause is refused the same way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-resource-type": "service" } }, "/hub/workflows/paused": { "get": { "summary": "List paused workflow runs", "description": "Runs waiting on human input. Each entry includes the run_id and the paused node's message; resume via runWorkflow. A pause with a form (`fields`) also appears as a `flow_input` action on its task; submitting that form resumes the run with the values at `$.resume`.", "operationId": "listPausedWorkflows", "parameters": [ { "name": "flow_subject", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ results: [...], results_total }" } }, "x-resource-type": "service" } }, "/hub/workflows/errored": { "get": { "summary": "List errored workflow runs", "description": "Runs that ended in an error, including the failing node id and lookup state at failure.", "operationId": "listErroredWorkflows", "parameters": [ { "name": "flow_subject", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ results: [...], results_total }" } }, "x-resource-type": "service" } }, "/hub/run-logs/search": { "post": { "summary": "Search run logs", "operationId": "searchRunLogs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conditions" ], "properties": { "conditions": { "type": "array", "description": "ANDed conditions over indexed fields: run_id, flow_topic, collection_topic, status (success|error|paused|in_progress), session_id, error, draft", "items": { "type": "object", "required": [ "field", "keyword" ], "properties": { "field": { "type": "string" }, "keyword": { "type": "string" } } } }, "limit": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{ results: [...] }" } }, "x-resource-type": "service" } }, "/hub/quiva-endpoints": { "get": { "summary": "List Quiva endpoints", "description": "Discover endpoint subjects referenced by quiva-endpoint nodes in data.subject.", "operationId": "listQuivaEndpoints", "responses": { "200": { "description": "{ results: [...], resultsTotal }" } }, "x-resource-type": "service" } }, "/hub/test-jpath": { "post": { "summary": "Test a JSONPath expression", "description": "Resolve a JSONPath expression or template object against sample lookup data using the real engine resolver. Use before building node payloads.", "operationId": "testJsonPath", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "path" ], "properties": { "data": { "description": "Sample lookup, e.g. { \"trigger\": {...}, \"MY_NODE\": {...} }" }, "path": { "description": "JSONPath string or template object, e.g. \"$.trigger.email\"" } } } } } }, "responses": { "200": { "description": "The resolved value" } }, "x-resource-type": "service" } }, "/hub/test-eval": { "post": { "summary": "Test an eval-node payload", "operationId": "testEval", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "params" ], "properties": { "code": { "type": "string", "description": "JavaScript expression, as in an eval node" }, "params": { "type": "object", "description": "Named params usable in code; values may be JSONPath resolved against lookup" }, "lookup": { "type": "object", "description": "Optional lookup data for resolving $.X references in params values" } } } } } }, "responses": { "200": { "description": "The eval result" } }, "x-resource-type": "service" } }, "/hub/test-http": { "post": { "summary": "Test an http/integration-node request", "operationId": "testHttp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "method" ], "properties": { "base_url": { "type": "string" }, "url": { "type": "string" }, "method": { "type": "string" }, "headers": { "type": "object" }, "params": { "type": "object" }, "query": { "type": "object" }, "data": { "description": "Request body" }, "lookup": { "type": "object", "description": "Optional lookup data for resolving $.X references in the request" } } } } } }, "responses": { "200": { "description": "{ status, statusText, headers, data }" } }, "x-resource-type": "service" } }, "/hub/workflows/{collection_topic}/{flow_topic}/node/{node_topic}": { "get": { "summary": "Get a node of a workflow", "description": "Reads one node of a workflow, as the editor does.", "operationId": "getWorkflowNode", "tags": [ "Workflows" ], "x-resource-type": "service", "parameters": [ { "name": "collection_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flow_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "node_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/workflows/{collection_topic}/{flow_topic}/integrity": { "get": { "summary": "Check a workflow's node and edge lists", "description": "Read-only report of node or edge id entries that cannot be addressed. Repair is an ordinary update.", "operationId": "getWorkflowIntegrity", "tags": [ "Workflows" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "collection_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flow_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/workflows/validate": { "post": { "summary": "Validate a workflow config", "description": "Reports what is wrong with a flow config without storing anything. The body is either a workflow with a config key or a bare config.", "operationId": "validateWorkflow", "tags": [ "Workflows" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/workflows/run-test": { "post": { "summary": "Run a workflow as a test", "description": "Runs a workflow in test mode and answers with the run detail.", "operationId": "runWorkflowTest", "tags": [ "Workflows" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/nodes/{collection_topic}/{node_topic}/projection": { "get": { "summary": "Get a node projection", "description": "Retrieves a workflow node with its payload data for client projection requests.", "operationId": "getNodeProjection", "tags": [ "Nodes" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "collection_topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "node_topic", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/run-stats": { "get": { "summary": "Get run statistics", "description": "Reads aggregate run statistics for the account's workflows.", "operationId": "getRunStats", "tags": [ "Workflows" ], "x-resource-type": "service", "x-path-derived": true, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/schedule": { "post": { "summary": "Schedule a flow", "description": "Arms a schedule that runs a published flow.", "operationId": "scheduleFlow", "tags": [ "Schedules" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/unschedule/{topic}": { "delete": { "summary": "Unschedule a flow", "description": "Removes a flow's schedule.", "operationId": "unscheduleFlow", "tags": [ "Schedules" ], "x-resource-type": "service", "parameters": [ { "name": "topic", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/scheduled": { "get": { "summary": "List scheduled flows", "description": "Lists the flows that have a schedule.", "operationId": "listScheduledFlows", "tags": [ "Schedules" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/eval-snippet": { "get": { "summary": "Get an eval snippet", "description": "Reads a stored eval snippet by id.", "operationId": "getEvalSnippet", "tags": [ "Eval snippets" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "patch": { "summary": "Store an eval snippet", "description": "Stores a named snippet on the account's config stream. The id has no dots or colons.", "operationId": "putEvalSnippet", "tags": [ "Eval snippets" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "delete": { "summary": "Delete an eval snippet", "description": "Removes a stored snippet.", "operationId": "deleteEvalSnippet", "tags": [ "Eval snippets" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/eval": { "post": { "summary": "Run a stored eval snippet", "description": "Runs a snippet stored on the account by id, with a bounded deadline. Never runs code taken from the request. The result is flat at the top of the body.", "operationId": "runEvalSnippet", "tags": [ "Eval snippets" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "deadline_ms": { "type": "integer" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/integrations/oauth-variables": { "get": { "summary": "Get OAuth variables", "description": "Reads the account's OAuth variables for integrations.", "operationId": "getOauthVariables", "tags": [ "Oauth" ], "x-resource-type": "service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "post": { "summary": "Save OAuth variables", "description": "Saves the account's OAuth variables for integrations.", "operationId": "saveOauthVariables", "tags": [ "Oauth" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace": { "get": { "summary": "List marketplace flows", "description": "Lists the flows available in the marketplace together with the owned ones.", "operationId": "listMarketplaceFlows", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page-size", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/product": { "get": { "summary": "Get a marketplace product", "description": "Reads one marketplace product.", "operationId": "getMarketplaceProduct", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/product-download-stats": { "get": { "summary": "Get product download statistics", "description": "Reads download counts for a product.", "operationId": "getMarketplaceProductDownloadStats", "tags": [ "Marketplace" ], "x-resource-type": "service", "x-path-derived": true, "parameters": [ { "name": "product_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/obtain-marketplace-product": { "post": { "summary": "Obtain a marketplace product", "description": "Obtains a product from the marketplace for the account.", "operationId": "obtainMarketplaceProduct", "tags": [ "Marketplace" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/workflows/download": { "post": { "summary": "Download a marketplace product", "description": "Copies a marketplace flow into the account.", "operationId": "downloadMarketplaceProduct", "tags": [ "Marketplace" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/rate-product": { "post": { "summary": "Rate a marketplace product", "description": "Records the caller's rating of a product.", "operationId": "rateMarketplaceProduct", "tags": [ "Marketplace" ], "x-resource-type": "service", "x-path-derived": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/submissions": { "get": { "summary": "List marketplace submissions", "description": "Lists the caller's submissions.", "operationId": "listMarketplaceSubmissions", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "post": { "summary": "Create a marketplace submission", "description": "Creates a submission.", "operationId": "createMarketplaceSubmission", "tags": [ "Marketplace" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/hub/marketplace/submissions/{topic}": { "get": { "summary": "View a marketplace submission", "description": "Reads one submission.", "operationId": "getMarketplaceSubmission", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "topic", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "product_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "patch": { "summary": "Update a marketplace submission", "description": "Only the user who created a submission can edit it.", "operationId": "updateMarketplaceSubmission", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "topic", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "delete": { "summary": "Delete a marketplace submission", "description": "Only the user who created a submission can delete it.", "operationId": "deleteMarketplaceSubmission", "tags": [ "Marketplace" ], "x-resource-type": "service", "parameters": [ { "name": "topic", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "CreateCollectionRequest": { "type": "object", "required": [ "name", "collection_type" ], "properties": { "name": { "type": "string", "description": "Name of the collection" }, "collection_type": { "type": "string", "enum": [ "node", "workflow" ], "description": "Type of the collection (node or workflow)" }, "description": { "type": "string", "description": "Optional description of the collection" } } }, "CreateCollectionResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the collection" }, "name": { "type": "string", "description": "Name of the collection" }, "collection_type": { "type": "string", "description": "Type of the collection (node or workflow)" }, "topic": { "type": "string", "description": "Hash of the collection name" }, "description": { "type": "string", "description": "Description of the collection" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "CreateNodeRequest": { "type": "object", "required": [ "collection", "data" ], "properties": { "collection": { "type": "string", "description": "Subject of the collection this node belongs to" }, "data": { "$ref": "#/components/schemas/NodeData" } } }, "CreateNodeResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the node" }, "collection": { "type": "string", "description": "Subject of the collection this node belongs to" }, "data": { "type": "object", "description": "Node data" }, "type": { "type": "string", "description": "Action type (created)" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "NodeData": { "description": "Node definition. id: unique, ^[a-zA-Z_][a-zA-Z0-9_:]*$, not a reserved word (trigger, static, RESOLVE_ERROR, RESOLVE_SUCCESS). payload is REQUIRED on every node type. Reference a node's output downstream via $.{id}.", "discriminator": { "propertyName": "node_type", "mapping": { "trigger": "#/components/schemas/TriggerNodeData", "agent": "#/components/schemas/AgentNodeData", "function": "#/components/schemas/FunctionNodeData", "integration": "#/components/schemas/IntegrationNodeData", "http": "#/components/schemas/HttpNodeData", "flow": "#/components/schemas/FlowNodeData", "eval": "#/components/schemas/EvalNodeData", "condition": "#/components/schemas/ConditionNodeData", "rules": "#/components/schemas/RulesNodeData", "map": "#/components/schemas/MapNodeData", "static": "#/components/schemas/StaticNodeData", "delay": "#/components/schemas/DelayNodeData", "schedule": "#/components/schemas/ScheduleNodeData", "input": "#/components/schemas/InputNodeData", "human-in-the-loop": "#/components/schemas/HumanInTheLoopNodeData", "quiva-endpoint": "#/components/schemas/QuivaEndpointNodeData", "error": "#/components/schemas/ErrorNodeData" } }, "oneOf": [ { "$ref": "#/components/schemas/TriggerNodeData" }, { "$ref": "#/components/schemas/AgentNodeData" }, { "$ref": "#/components/schemas/FunctionNodeData" }, { "$ref": "#/components/schemas/IntegrationNodeData" }, { "$ref": "#/components/schemas/HttpNodeData" }, { "$ref": "#/components/schemas/FlowNodeData" }, { "$ref": "#/components/schemas/EvalNodeData" }, { "$ref": "#/components/schemas/ConditionNodeData" }, { "$ref": "#/components/schemas/RulesNodeData" }, { "$ref": "#/components/schemas/MapNodeData" }, { "$ref": "#/components/schemas/StaticNodeData" }, { "$ref": "#/components/schemas/DelayNodeData" }, { "$ref": "#/components/schemas/ScheduleNodeData" }, { "$ref": "#/components/schemas/InputNodeData" }, { "$ref": "#/components/schemas/HumanInTheLoopNodeData" }, { "$ref": "#/components/schemas/QuivaEndpointNodeData" }, { "$ref": "#/components/schemas/ErrorNodeData" } ] }, "NodeOptions": { "type": "object", "description": "Execution options for function/flow/integration/http nodes", "properties": { "flat_map": { "type": "boolean", "description": "Flatten array results" }, "backoff_ms": { "type": "integer", "description": "Delay between retries (ms)" }, "timeout": { "type": "integer", "description": "ms" }, "attempts": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Retry attempts on failure" }, "ignore_response_codes": { "type": "array", "description": "HTTP status codes treated as success", "items": { "type": "integer" } } } }, "Edge": { "type": "object", "required": [ "id", "source", "target" ], "properties": { "id": { "type": "string" }, "source": { "type": "string", "description": "Source node id" }, "target": { "type": "string", "description": "Target node id" } } }, "WorkflowConfig": { "type": "object", "description": "The execution graph. Must be acyclic (not server-checked). Nodes run in topological order; condition nodes can alter the path.", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/NodeWorkflow" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" } }, "static": { "type": "object", "description": "Static variables accessible via $.static" }, "result": { "type": "string", "description": "JSONPath selecting the run's return value, e.g. '$.FINAL_NODE.result'. Without it the run returns the full step log array." }, "options": { "type": "object", "properties": { "run_type": { "type": "string", "enum": [ "normal", "debounced", "ordered" ] }, "order_on": { "type": "string", "description": "JSONPath key for run_type=ordered" }, "debounce_on": { "type": "string", "description": "JSONPath key for run_type=debounced" }, "debounce_time": { "type": "integer", "description": "ms" }, "debounce_max": { "type": "integer", "description": "ms" } } } } }, "CreateWorkflowRequest": { "type": "object", "required": [ "name", "collection" ], "properties": { "name": { "type": "string", "description": "Unique within the collection" }, "description": { "type": "string" }, "collection": { "type": "string", "description": "Collection subject: ms.hub.config.collection.workflow.{collection_id} (from listCollections)", "pattern": "^ms\\.hub\\.config\\.collection\\.workflow\\." }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "secrets": { "type": "array", "description": "Secret identifiers used by this workflow", "items": { "type": "string" } } } }, "CreateWorkflowResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "collection": { "type": "string", "description": "Subject of the collection this workflow belongs to" }, "description": { "type": "string", "description": "Description of the workflow" }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "RunWorkflowRequest": { "type": "object", "required": [ "subject" ], "properties": { "subject": { "type": "string", "pattern": "^ms\\.hub\\.config\\.workflow\\.", "description": "Workflow subject. Published: ms.hub.config.workflow.{collection}.{flow} (NO 'published' segment - get it from listWorkflows version=published). Draft: ms.hub.config.workflow.draft.{collection}.{flow}." }, "trigger": { "type": "object", "description": "Run input, referenced in nodes via $.trigger" }, "triggers": { "type": "array", "description": "Batch execution (use either trigger or triggers)", "items": { "type": "object" } }, "await": { "type": "boolean", "default": false, "description": "true = wait for completion and return results; false = return tracking_id immediately" }, "enable_log": { "type": "boolean", "default": true, "description": "Store detailed run logs (searchable via searchRunLogs)" }, "knowledge": { "type": "array", "description": "Knowledge URIs for agents: kv://, obj://, str://, sid://, dta://", "items": { "type": "string" } }, "session_id": { "type": "string", "description": "Agent conversation continuity; omit for new sessions" }, "run_id": { "type": "string", "description": "Tracking id of a paused run to resume (human-in-the-loop)" }, "retry": { "type": "boolean", "description": "Retry a failed run" } } }, "RunWorkflowResponse": { "oneOf": [ { "type": "object", "properties": { "trackingId": { "type": "string", "description": "ID for tracking the workflow execution" }, "result": { "type": "object", "description": "Result of the workflow execution" } } }, { "type": "string", "description": "Status message for debounced or ordered executions" } ] }, "PublishWorkflowRequest": { "type": "object", "required": [ "subject" ], "properties": { "subject": { "type": "string", "description": "Draft subject: ms.hub.config.workflow.draft.{collection}.{flow}", "pattern": "^ms\\.hub\\.config\\.workflow\\.draft\\." }, "commit": { "type": "string", "description": "Commit message" } } }, "UpdateCollectionRequest": { "type": "object", "required": [ "subject" ], "properties": { "subject": { "type": "string", "description": "Subject of the collection to update" }, "description": { "type": "string", "description": "Updated description of the collection" } } }, "UpdateNodeRequest": { "type": "object", "required": [ "subject", "data" ], "properties": { "data": { "$ref": "#/components/schemas/NodeData" }, "archived": { "type": "boolean", "description": "Whether the node is archived" } } }, "UpdateMultiNodeRequest": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateNodeRequest" } }, "UpdateMultiNodeResponse": { "type": "array", "items": { "type": "object", "properties": { "node": { "$ref": "#/components/schemas/UpdateNodeRequest" }, "result": { "type": "string", "description": "Result of the update operation" } } } }, "UpdateMultiNodeErrorResponse": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "properties": { "node": { "$ref": "#/components/schemas/UpdateNodeRequest" }, "result": { "type": "string", "description": "Result of the update operation with error messages" } } } }, "error": { "type": "string", "description": "General error message" } } }, "UpdateWorkflowRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "archived": { "type": "boolean", "description": "Archived workflows cannot be executed" }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "secrets": { "type": "array", "items": { "type": "string" } } } }, "UpdateWorkflowResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "description": { "type": "string", "description": "Description of the workflow" }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "GetCollectionResponse": { "type": "object", "required": [ "name", "topic", "subject", "sequence", "type", "modified" ], "properties": { "name": { "type": "string", "description": "Name of the collection" }, "collection_type": { "type": "string", "description": "Type of the collection (node or workflow)" }, "topic": { "type": "string", "description": "Hash of the collection name" }, "description": { "type": "string", "description": "Description of the collection" }, "subject": { "type": "string", "description": "Subject identifier for the collection" }, "sequence": { "type": "integer", "description": "The sequence number of the last message for this collection on the stream" }, "modified": { "$ref": "#/components/schemas/Modified" }, "type": { "type": "string", "description": "Last event type - created or updated", "enum": [ "created", "updated" ] } } }, "Modified": { "type": "integer", "description": "Timestamp of last modification" }, "GetNodeResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the node" }, "data": { "$ref": "#/components/schemas/NodeData" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "GetWorkflowResponse": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "description": { "type": "string", "description": "Description of the workflow" }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "modified": { "$ref": "#/components/schemas/Modified" } } }, "ListNodesResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the node" }, "data": { "$ref": "#/components/schemas/NodeData" }, "modified": { "$ref": "#/components/schemas/Modified" } } } }, "results_total": { "type": "integer", "description": "Total number of results" } } }, "ListWorkflowsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject identifier for the workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "description": { "type": "string", "description": "Description of the workflow" }, "config": { "$ref": "#/components/schemas/WorkflowConfig" }, "modified": { "$ref": "#/components/schemas/Modified" } } } }, "results_total": { "type": "integer", "description": "Total number of results" } } }, "SuccessResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "IntegrationOauthConfig": { "type": "object", "required": [ "integration_id", "name", "scopes", "client_id", "client_secret", "auth_url", "token_url", "redirect_url" ], "properties": { "integration_id": { "type": "string", "description": "Unique identifier for the integration" }, "name": { "type": "string", "description": "Name of the OAuth integration" }, "scopes": { "type": "string", "description": "Comma-separated list of OAuth scopes", "example": "read,write,admin" }, "client_id": { "type": "string", "description": "OAuth client ID" }, "client_secret": { "type": "string", "description": "OAuth client secret" }, "auth_url": { "type": "string", "format": "uri", "description": "Authorization URL for the OAuth flow" }, "token_url": { "type": "string", "format": "uri", "description": "Token URL to exchange authorization code for access token" }, "redirect_url": { "type": "string", "format": "uri", "description": "Redirect URL used in the OAuth flow" } } }, "OauthConfigBasicData": { "type": "object", "properties": { "integration_id": { "type": "string", "example": "slack" }, "name": { "type": "string", "example": "Slack API" }, "scopes": { "type": "string", "example": "channels:read" }, "subject": { "type": "string", "example": "ms.integration.oauth.config.slack" } }, "example": { "integration_id": "slack", "name": "Slack API", "scopes": "channels:read", "subject": "ms.integration.oauth.config.slack" } }, "OauthConfigList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/OauthConfigBasicData" } }, "results_total": { "type": "integer", "example": 2 } }, "example": { "results": [ { "integration_id": "slack", "name": "Slack API", "scopes": "channels:read", "subject": "ms.integration.oauth.config.slack" }, { "integration_id": "xero", "name": "Xero API's", "scopes": "email,openid,profile,assets,assets.read,files,files.read,projects,projects.read", "subject": "ms.integration.oauth.config.xero" } ], "results_total": 2 } }, "OauthConnection": { "type": "object", "properties": { "access_token": { "type": "string", "description": "OAuth access token", "example": "eyJhbGciOiJSUzI1Ni..." }, "token_type": { "type": "string", "description": "Token type (usually Bearer)", "example": "Bearer" }, "refresh_token": { "type": "string", "description": "OAuth refresh token", "example": "ulpL_..." }, "expiry": { "type": "string", "format": "date-time", "description": "Token expiration time", "example": "2025-05-29T17:09:39.816102+01:00" }, "expires_in": { "type": "integer", "description": "Token expires in seconds", "example": 1800 }, "sequence": { "type": "integer", "description": "Message sequence number", "example": 85 }, "subject": { "type": "string", "description": "Message subject", "example": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo" }, "modified": { "type": "integer", "description": "Last modified timestamp", "example": 1748533179 } }, "example": { "access_token": "eyJhbGciOiJSUzI1Ni...", "expires_in": 1800, "expiry": "2025-05-29T17:09:39.816102+01:00", "modified": 1748533179, "refresh_token": "ulpL_...", "sequence": 85, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo", "token_type": "Bearer" } }, "OauthConnectionsList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/OauthConnection" } }, "results_total": { "type": "integer", "example": 2 } }, "example": { "results": [ { "access_token": "eyJhbGciOiJSUzI1Ni...", "expires_in": 1800, "expiry": "2025-05-29T17:09:39.816102+01:00", "modified": 1748533179, "refresh_token": "ulpL_...", "sequence": 85, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.demo", "token_type": "Bearer" }, { "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 1800, "expiry": "2025-05-29T17:11:54.397804+01:00", "modified": 1748533314, "refresh_token": "pSn5h...", "sequence": 86, "subject": "ms.integration.oauth.AC75JGNMJHTRQNXCBDMIAJCJ57HAEWP2RGWXJCIFFGW2K64OKG267A2D.xero.maria", "token_type": "Bearer" } ], "results_total": 2 } }, "OauthLoginResponse": { "type": "object", "properties": { "oauth_url": { "type": "string", "description": "OAuth authorization URL to redirect user to", "example": "https://slack.com/oauth/v2/authorize?client_id=123456789.987654321&scope=channels:read&state=abc123xyz&redirect_uri=https://api.example.com/hub/integrations/oauth-callback" } }, "example": { "oauth_url": "https://slack.com/oauth/v2/authorize?client_id=123456789.987654321&scope=channels:read&state=abc123xyz&redirect_uri=https://api.example.com/hub/integrations/oauth-callback" } }, "NodeWorkflow": { "type": "object", "required": [ "id", "data" ], "properties": { "id": { "type": "string", "description": "Must equal data.id" }, "data": { "$ref": "#/components/schemas/NodeData" }, "position": { "type": "object", "description": "Optional visual editor position { x, y }" } } }, "NodeDataCommon": { "type": "object", "required": [ "id", "node_type", "payload" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "TriggerNodeData": { "description": "Entry-point metadata for the visual editor. SKIPPED at runtime — optional; run input arrives via the run request 'trigger' field ($.trigger), not through this node.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "trigger" ] }, "trigger_type": { "type": "string", "enum": [ "manual", "schedule", "webhook", "gateway", "embed", "email", "object-store", "record", "task", "email-delivery", "mail" ], "description": "How the flow starts. `email-delivery` fires on delivery events of emails sent from templates. `mail` fires from a Microsoft 365 mail automation with the filed email, its attachment files riding as knowledge. `task` starts from a task event." }, "payload": { "type": "object", "additionalProperties": true, "description": "Config varies by `trigger_type`; `{}` for manual. For `email-delivery`: `event_type` (array of `bounce`, `blocked`, `dropped`, `undeliverable`, `deferred`, and other delivery events; default is bounce, blocked, dropped and undeliverable, `deferred` is left out because it is usually temporary), `class` (only emails of this class) and `template_key` (only emails sent from this template). For `task`: `space_id`, `event_type`, `folder`, `status`, `status_from`, `status_to`, `allow_self_trigger`. The trigger data reaches the flow at `$.trigger`." } } } ] }, "AgentNodeData": { "description": "Invoke an LLM agent. The inline definition MUST be nested under payload.agent — flat payloads (api_key/llm_provider/model at payload top level) are silently dropped at runtime and the node fails with 'a subject, node_subject or agent property is required'. IMPORTANT: the node output at $.{id}.result is a JSON-ENCODED STRING even when output_schema is set — add an eval node to JSON.parse it before branching on its fields.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "agent" ] }, "payload": { "type": "object", "description": "One of 'agent' (inline definition), 'subject' (saved agent subject) or 'node_subject' (agent node template) is required. prompt/await live at this level, NOT inside agent.", "properties": { "agent": { "type": "object", "required": [ "name", "llm_provider", "model" ], "properties": { "name": { "type": "string", "description": "Agent identifier, e.g. 'kyc_risk_assessment'" }, "llm_provider": { "type": "string", "enum": [ "claude", "anthropic" ], "description": "The invoke handler only supports claude/anthropic" }, "model": { "type": "string", "description": "Platform catalog alias, e.g. 'claude-sonnet-4-6', 'claude-haiku-4-5'" }, "description": { "type": "string" }, "behaviour": { "type": "string", "description": "System prompt" }, "output_schema": { "type": "object", "description": "Flat map of field -> short description; forces structured JSON output (still delivered as a JSON string in result)", "additionalProperties": { "type": "string" } }, "has_tools": { "type": "boolean" }, "tools": { "type": "array", "description": "mcp://integration, fun://function, bit://tool (e.g. bit://web_search)", "items": { "type": "string" } }, "knowledge": { "type": "array", "description": "kv://bucket/doc, obj://bucket/doc, str://stream/start/end, sid://session_id, dta://data", "items": { "type": "string" } }, "timeout": { "type": "number", "description": "seconds" } } }, "subject": { "type": "string", "description": "Saved agent subject (alternative to inline 'agent')" }, "node_subject": { "type": "string", "description": "Agent node template subject (alternative to inline 'agent')" }, "prompt": { "description": "string or object; supports JSONPath, e.g. 'Summarise |$.trigger.text'. Empty = the raw trigger is used as the prompt.", "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "await": { "type": "boolean" }, "knowledge": { "type": "array", "items": { "type": "string" } } } } } } ] }, "FunctionNodeData": { "description": "Invoke a compute function. subject is REQUIRED and must exist — discover via GET /compute/functions.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "required": [ "subject" ], "properties": { "node_type": { "type": "string", "enum": [ "function" ] }, "subject": { "type": "string", "pattern": "^ms\\.compute\\." }, "payload": { "description": "Function input (any JSON); JSONPath supported, e.g. '$.PREV_NODE'" }, "response_map": { "description": "Optional JSONPath mapping applied to the function output" }, "options": { "$ref": "#/components/schemas/NodeOptions" } } } ] }, "IntegrationNodeData": { "description": "HTTP request to a third-party API, optionally via an OAuth connection. Result shape: { status, statusText, headers, data }. 4xx/5xx responses become node errors (tolerate/retry via options).", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "integration" ] }, "integration_id": { "type": "string", "description": "e.g. 'slack'" }, "request_type_id": { "type": "string", "description": "e.g. 'post_chat_postMessage'" }, "oauth": { "type": "string", "description": "OAuth connection identifier" }, "payload": { "$ref": "#/components/schemas/HttpPayload" }, "options": { "$ref": "#/components/schemas/NodeOptions" } } } ] }, "HttpNodeData": { "description": "Plain HTTP request (no OAuth metadata). Same payload and behaviour as integration.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "http" ] }, "payload": { "$ref": "#/components/schemas/HttpPayload" }, "options": { "$ref": "#/components/schemas/NodeOptions" } } } ] }, "HttpPayload": { "type": "object", "required": [ "url", "method" ], "description": "JSONPath supported in all fields. IMPORTANT: the base URL key is snake_case 'base_url' — a 'baseURL' key is silently ignored.", "properties": { "base_url": { "type": "string", "description": "Joined with url; snake_case, NOT baseURL" }, "url": { "type": "string", "description": "Path or full URL" }, "method": { "type": "string", "description": "GET/POST/PUT/DELETE/PATCH... (case-insensitive)" }, "data": { "type": "object", "description": "Request body" }, "params": { "type": "object" }, "query": { "type": "object" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "timeout": { "type": "integer", "description": "ms (default 30000)" } } }, "FlowNodeData": { "description": "Invoke another published workflow as a sub-flow. subject is REQUIRED and must exist.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "required": [ "subject" ], "properties": { "node_type": { "type": "string", "enum": [ "flow" ] }, "subject": { "type": "string", "pattern": "^ms\\.hub\\.config\\.workflow\\.", "description": "Sub-workflow subject: ms.hub.config.workflow.{collection}.{flow} (published form, no 'published' segment); must exist" }, "payload": { "description": "Passed as the sub-flow trigger; JSONPath supported" }, "await": { "type": "boolean", "description": "Wait for sub-flow completion" }, "response_map": { "description": "Optional JSONPath mapping over the sub-flow output" }, "options": { "$ref": "#/components/schemas/NodeOptions" } } } ] }, "EvalNodeData": { "description": "Run a JavaScript expression over named params.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "eval" ] }, "payload": { "type": "object", "required": [ "code", "params" ], "properties": { "code": { "type": "string", "description": "Plain JavaScript expression — JSONPath is NOT resolved inside code" }, "params": { "type": "object", "description": "Named params usable in code; each VALUE is JSONPath-resolved, e.g. { \"c\": \"$.AGENT.result\" }", "additionalProperties": true } } }, "options": { "$ref": "#/components/schemas/NodeOptions" } } } ] }, "ConditionNodeData": { "description": "Branching. Evaluates rules and activates the listed node ids; non-selected branches are skipped. Reserved targets: RESOLVE_SUCCESS (end flow ok), RESOLVE_ERROR (fail flow). Any other target must be an existing node id, and you should also add edges from this node to each then/else target.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "condition" ] }, "payload": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "if": { "type": "string", "description": "JSONPath boolean expression, e.g. \"$.FETCH.status == 200\"" }, "then": { "type": "array", "items": { "type": "string" } }, "else": { "type": "array", "items": { "type": "string" } } } } } } } } } ] }, "RulesNodeData": { "description": "Evaluate a rules object against facts/context; output is { : outcome }.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "rules" ] }, "payload": { "type": "object", "required": [ "rules" ], "properties": { "rules": { "type": "object", "description": "Rules map (same engine as condition nodes)" }, "facts": { "type": "object" }, "context": { "type": "object" } } } } } ] }, "MapNodeData": { "description": "Reshape data: the payload template is JSONPath-resolved and becomes the node output.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "map" ] }, "payload": { "description": "Object or array template; string values may be JSONPath references", "oneOf": [ { "type": "object" }, { "type": "array", "items": {} } ] }, "options": { "type": "object", "properties": { "flat_map": { "type": "boolean", "description": "Flatten array results" } } } } } ] }, "StaticNodeData": { "description": "Merge literal values into $.static. LITERALS ONLY — JSONPath is not resolved in this payload.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "static" ] }, "payload": { "type": "object", "additionalProperties": true } } } ] }, "DelayNodeData": { "description": "Pause the branch for time_ms milliseconds. The node type is 'delay' — 'wait' is NOT a valid type (the engine silently ignores it).", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "delay" ] }, "payload": { "type": "object", "required": [ "time_ms" ], "properties": { "time_ms": { "type": "integer", "minimum": 0, "description": "Milliseconds; supports JSONPath" } } } } } ] }, "ScheduleNodeData": { "description": "Schedule another workflow run for later.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "schedule" ] }, "payload": { "type": "object", "required": [ "flow_subject", "trigger" ], "properties": { "flow_subject": { "type": "string", "description": "Workflow subject to schedule; supports JSONPath" }, "trigger": { "description": "Trigger data for the scheduled run; supports JSONPath" }, "trigger_in": { "type": "string", "description": "Relative delay, e.g. '5m', '1h', '2d'", "pattern": "^\\d+[smhd]$" }, "trigger_on": { "type": "string", "description": "Cron expression or ISO date" } } } } } ] }, "InputNodeData": { "description": "Pause the flow for human input: creates an escalation task (emailing assignees) and pauses. Resume via runWorkflow with the run_id and the human response as trigger — that response becomes this node's output.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "input" ] }, "payload": { "$ref": "#/components/schemas/EscalationPayload" } } } ] }, "HumanInTheLoopNodeData": { "description": "Alias of 'input': pause for human approval/input via an escalation task.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "human-in-the-loop" ] }, "payload": { "$ref": "#/components/schemas/EscalationPayload" } } } ] }, "EscalationPayload": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Prompt for the human; supports JSONPath" }, "title": { "type": "string", "description": "Escalation task title" }, "description": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "string", "description": "Comma-separated user ids; each is notified by email" }, "fields": { "description": "A JSON Schema (type `object` with `properties`) or a `$.` reference to one. With it the hub writes one `flow_input` action on the task and the task's assignees answer it as a form. Submitting resumes the run with the values at `$.resume`, marks the action done and posts the answer as a task comment. Without `fields` the run pauses as before and is resumed from Monitor.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" } ] }, "task_id": { "type": "string", "description": "Ask on this existing task instead of raising a new one." }, "keep_status": { "type": "boolean", "description": "Leaves the form action out of the task's status automation." } } }, "QuivaEndpointNodeData": { "description": "Invoke a Quiva endpoint. subject is REQUIRED — discover via GET /hub/quiva-endpoints.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "required": [ "subject" ], "properties": { "node_type": { "type": "string", "enum": [ "quiva-endpoint" ] }, "subject": { "type": "string" }, "payload": { "description": "Passed to the endpoint; JSONPath supported" } } } ] }, "ErrorNodeData": { "description": "Terminate the flow with an error status code and message.", "allOf": [ { "$ref": "#/components/schemas/NodeDataCommon" }, { "type": "object", "properties": { "node_type": { "type": "string", "enum": [ "error" ] }, "payload": { "type": "object", "required": [ "status_code" ], "properties": { "status_code": { "type": "integer" }, "message": { "type": "string" } } } } } ] } }, "parameters": { "collectionTopic": { "name": "collection_topic", "in": "path", "description": "The topic is a hash of the name that was used when a collection was created", "required": true, "schema": { "type": "string" }, "example": "1234567890" }, "flowTopic": { "name": "flow_topic", "in": "path", "description": "Flow topic - hash of the names the node was created with", "required": true, "schema": { "type": "string" }, "example": "21312322" }, "nodeTopic": { "name": "node_topic", "in": "path", "description": "Node topic - hash of the names the node was created with", "required": true, "schema": { "type": "string" }, "example": "98765432" }, "collectionType": { "name": "collection_type", "in": "path", "description": "List only 'node' or only 'workflow' collections. If this parameter is omitted, both will be listed", "required": false, "schema": { "type": "string", "enum": [ "node", "workflow" ] }, "example": "node" }, "integrationId": { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Integration identifier", "example": "slack" }, "connectionId": { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection identifier", "example": "maria" }, "queryCollectionType": { "name": "collection_type", "in": "query", "description": "List only 'node' or only 'workflow' collections. If this parameter is omitted, both will be listed", "required": false, "schema": { "type": "string", "enum": [ "node", "workflow" ] }, "example": "node" }, "queryDraftFlag": { "name": "draft", "in": "query", "description": "Draft flag", "required": false, "schema": { "type": "boolean" }, "example": true } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "oauth2": { "type": "oauth2", "description": "API integration client credentials. Tokens only work on the task-sync routes in workspaces.", "flows": { "clientCredentials": { "tokenUrl": "https://api.quiva.ai/oauth/token", "scopes": {} } } } }, "responses": { "BadRequest": { "description": "Invalid request or validation failure, e.g. { \"error\": \"duplicate node id found: CODE_EXPERT\" }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "tags": [ { "name": "Collections", "description": "Operations related to collections" }, { "name": "Nodes", "description": "Operations related to nodes" }, { "name": "Workflows", "description": "Operations related to workflows" }, { "name": "Oauth", "description": "Oauth configurations and connections" }, { "name": "Schedules" }, { "name": "Eval snippets" }, { "name": "Marketplace" } ] }