Flow Sharing and Integration

Flows can run from the Flow editor, Peers, client APIs, public share tokens, schedules, and tool webhook triggers. This page summarizes the supported integration surfaces and the response shapes you should expect.

Visibility and Access

Flows can be private or shared inside the workspace. Version publishing also preserves visibility metadata such as shared users and groups.

For API execution, access is controlled by the route you use:

• /v1/flow/*: authenticated dashboard/internal user routes.
• /v1/client/flow/*: client-facing execution route.
• /v1/flow/share/*: public token routes.

Peer Integration

A Flow can be attached to a Peer as an action/tool. When the Peer invokes it, the Flow receives conversation context and can return the Final step output back to the Peer response.

Peer-triggered Flows commonly use:

• peer.message triggers for direct message handling.
• peer.action triggers for tool-like action inputs.
• Chat-only steps such as user-approval, client-tool, show-form, add-widget-to-message, and end-session when conversation/message context is available.

API Execution

Dashboard/Internal Execution

POST /v1/flow/execute/:flowId

Request body:

{
  "inputs": {
    "customerId": "cus_123",
    "topic": "renewal"
  },
  "returnExecutionMetadata": true
}

Completed response with metadata:

{
  "status": "completed",
  "appRunId": "run_id",
  "output": {
    "summary": "Renewal risk is low"
  }
}

Without returnExecutionMetadata, the response is the Final step output object directly.

Client API Execution

POST /v1/client/flow/:flowId/execute

The Flow must include an api trigger. Pass inputs directly in the request body:

{
  "customerId": "cus_123",
  "topic": "renewal"
}

Use ?version=<number-or-latest> when you need to execute a specific published version.

Public Share Token Execution

GET /v1/flow/share/:token
POST /v1/flow/share/execute/:token
POST /v1/flow/share/file/:token

Share-token execution also accepts the Flow input object directly in the request body.

Waiting Runs

Some steps intentionally pause execution:

• user-approval waits for an approve/reject decision.
• client-tool waits for a client-side tool result.

Paused executions return waiting metadata, including an appRunId that can be resumed:

POST /v1/flowrun/resume/:appRunId

Approval resume body:

{
  "decision": "approve"
}

Client tool resume body:

{
  "toolResult": {
    "executionId": "flow_execution_id",
    "success": true,
    "output": {
      "result": "local value"
    }
  }
}

When a paused Flow is running inside a Peer conversation, the chat UI normally resumes it through the message approval or client-tool UI.

Schedules

Schedules are configured on a Flow with a cron expression and optional default inputs.

GET /v1/flow/:flowId/schedule
POST /v1/flow/:flowId/schedule
POST /v1/flow/:flowId/schedule-cancel

Schedule body:

{
  "cron": "0 9 * * 1",
  "data": {
    "inputs": {
      "reportType": "weekly"
    }
  }
}

The scheduler creates an app.run job for the Flow and passes the configured inputs when it fires.

Webhooks

Flows can send outbound webhooks with the HTTP Request step.

Inbound webhook triggers come from installed tools that expose trigger definitions. These appear as dynamic trigger types named webhook.<toolTriggerId>. When a Flow with such a trigger is saved, Cognipeer registers the external webhook through the tool trigger. When the trigger is removed, Cognipeer attempts to unregister it.

Files, Logs, and Diagnostics

Useful supporting routes:

POST /v1/flow/file
GET /v1/flow/:flowId/logs
GET /v1/flowrun/details/:runId
GET /v1/flowrun/poll/:runId
GET /v1/flowrun/inputs/:runId
GET /v1/flowrun/outputs/:runId
GET /v1/flowrun/errorDetails/:runId
GET /v1/flowrun/steps/:runId
GET /v1/flowrun/context/:runId
GET /v1/flowrun/credit-details/:runId

Use the lightweight poll route for status checks and the detailed/context routes only when you need deeper debugging data.

Import, Export, and Clone

POST /v1/flow/:flowId/clone
GET /v1/flow/:flowId/export
POST /v1/flow/import

Export returns a JSON Flow definition attachment. Import creates a Flow from a definition payload.

Best Practices

• Add an api trigger to Flows intended for /v1/client/flow/:flowId/execute.
• Use returnExecutionMetadata when external systems need the run ID for audit, polling, or resume.
• Keep Final step outputs stable for API consumers.
• Validate external payloads early before calling tools or models.
• Use published versions for production integrations and draft executions only for editor previews.