Flow API

Flow APIs execute, manage, inspect, and resume Cognipeer Flows. Client-facing execution is under /v1/client/flow; dashboard/internal operations are under /v1/flow and /v1/flowrun.

Execute Flow: Client API

Execute a specific Flow identified by its ID. The Flow processes provided inputs and returns outputs defined in the Final step.

Request

POST /v1/client/flow/:_id/execute

The Flow must contain an api trigger.

Request Body

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

Pass Flow inputs directly in the body. You can also use ?version=<number-or-latest> to execute a specific published version.

Response

By default, the response is the Final step output object:

{
  "summary": "Renewal risk is low",
  "score": 82
}

If the Flow pauses for a user approval or client tool call, the response can include a waiting status, appRunId, and waitState/pendingAction metadata that your client must resume.

Execute Flow: Dashboard/Internal API

POST /v1/flow/execute/:flowId

Request body:

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

When returnExecutionMetadata is true, completed executions return:

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

Public Token Execution

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

The execute endpoint accepts the Flow input object directly in the request body.

Flow Management

GET /v1/flow/preferences
POST /v1/flow/step-field-items
GET /v1/flow
POST /v1/flow
GET /v1/flow/:_id
PATCH /v1/flow/:_id
DELETE /v1/flow/:_id
POST /v1/flow/:_id/autosave
POST /v1/flow/:_id/publish
POST /v1/flow/enhance
POST /v1/flow/:_id/enhance
POST /v1/flow/:appId/clone
GET /v1/flow/:appId/export
POST /v1/flow/import
POST /v1/flow/file

Scheduling and Logs

GET /v1/flow/:_id/schedule
POST /v1/flow/:_id/schedule
POST /v1/flow/:_id/schedule-cancel
GET /v1/flow/:_id/logs

The schedule body uses cron and optional data fields:

{
  "cron": "0 * * * *",
  "data": {
    "inputs": {
      "reportType": "hourly"
    }
  }
}

Run Inspection and Resume

GET /v1/flowrun/overview/:appId
GET /v1/flowrun/details/:id
POST /v1/flowrun/resume/:id
GET /v1/flowrun/poll/:id
GET /v1/flowrun/light/:appId
GET /v1/flowrun/summary/:id
GET /v1/flowrun/detailed/:id
GET /v1/flowrun/:appId
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/minimal-details/:runId
GET /v1/flowrun/credit-details/:runId

Resume a waiting User Approval run:

POST /v1/flowrun/resume/:appRunId

{
  "decision": "approve"
}

Resume a waiting Client Tool run:

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

Versions

GET /v1/flow/:appId/versions
GET /v1/flow/:appId/versions/:version
POST /v1/flow/:appId/versions/:version/publish
POST /v1/flow/:appId/versions/:version/set-latest
POST /v1/flow/:appId/versions/:version/rollback
POST /v1/flow/:appId/versions/:version/unpublish
DELETE /v1/flow/:appId/versions/:version

Only published versions can be set as latest. Published versions must be unpublished before deletion.