--- title: "Run a flow now" method: POST path: "/syncs/{syncid}/flows/{flowid}/execute" tags: ["Syncs"] --- # Run a flow now `POST /syncs/{syncid}/flows/{flowid}/execute` ## Request - Base URL: `https://api.chift.eu` - URL: `https://api.chift.eu/syncs/{syncid}/flows/{flowid}/execute` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Starts the flow immediately. Pass several consumers to run it as configured for each of them, or exactly one consumer together with settings — settings apply to a single consumer's run. `GET /syncs/{syncid}/flows/{flowid}/settings` lists the settings this flow accepts. The response echoes the settings that were applied and anything worth knowing about the run. Send `preflight: true` to get that answer without starting anything: the same request is checked the same way, and a refusal comes back as a blocking warning instead of an error. ## Path parameters - `syncid` string, required - `flowid` string, required ## Request body - ExecuteFlowRequest: Run a flow now. Settings apply to a single consumer: pass several only for a plain run with no settings. - `consumers` union[]: Consumer ids, or the single value 'all' for every consumer of the sync. - union - string, uuid - string - `settings` FlowSettings: The settings one execution was started with. Shared by every sync and never subclassed, so ``flow.settings.`` has one static type everywhere. Per-sync variance lives in :class:`FlowSettingsSpec` (which settings a sync supports, its tooltips, its extra fields) — never in this model. Read it through the derived properties rather than the raw fields: they are the only thing a sync should branch on, and they are what keeps a setting's scope from leaking into another's. - `force_from_date` string, date, nullable - `force_to_date` string, date, nullable - `write_mode` 'normal' | 'debug' | 'preview': What an execution may write. Its scope is writes and nothing else: it never changes which period runs, what gets skipped, or how much is logged. ``PREVIEW`` is ``DEBUG`` plus a recorder. - `import_mode` 'normal' | 'force_reimport' | 'IMPORT_ONLY_MISSING_DAYS' | 'REIMPORT_ENTIRE_PERIOD': How an execution interprets the sync state already recorded in the datastores. ``NORMAL`` treats the datastore as authoritative: anything not recorded as a success is retried. ``FORCE_REIMPORT`` ignores those records and re-exports everything in range; each sync decides how its own tracking datastores are reconciled. Its scope is state, not period: it never chooses which dates run, and it never deletes anything on its own. - `verbose_logs` boolean - `extra` object - `preflight` boolean: Check the request without starting anything. Everything that decides whether the run may start is evaluated, and a refusal comes back as a blocking warning rather than an error, so you can warn someone before they confirm. - `only` OnlyObjects: Book these source objects of one capability of an agentic sync, whatever its cadence; again when ``import_mode`` is ``force_reimport``. - `capability` string, required: The capability's key, e.g. `spend_to_accounting.SupplierInvoices`. - `ids` string[], required: The source objects' ids. - `scope` object, nullable: Where the ids are, for a capability whose objects are only unique within something the consumer runs several of, e.g. `{"location_id": "paris"}`. Exactly the keys the capability is scoped on. ## Response `200` Successful Response - ExecuteFlowResponse - `resolved_settings` FlowSettings, required: The settings one execution was started with. Shared by every sync and never subclassed, so ``flow.settings.`` has one static type everywhere. Per-sync variance lives in :class:`FlowSettingsSpec` (which settings a sync supports, its tooltips, its extra fields) — never in this model. Read it through the derived properties rather than the raw fields: they are the only thing a sync should branch on, and they are what keeps a setting's scope from leaking into another's. - `force_from_date` string, date, nullable - `force_to_date` string, date, nullable - `write_mode` 'normal' | 'debug' | 'preview': What an execution may write. Its scope is writes and nothing else: it never changes which period runs, what gets skipped, or how much is logged. ``PREVIEW`` is ``DEBUG`` plus a recorder. - `import_mode` 'normal' | 'force_reimport' | 'IMPORT_ONLY_MISSING_DAYS' | 'REIMPORT_ENTIRE_PERIOD': How an execution interprets the sync state already recorded in the datastores. ``NORMAL`` treats the datastore as authoritative: anything not recorded as a success is retried. ``FORCE_REIMPORT`` ignores those records and re-exports everything in range; each sync decides how its own tracking datastores are reconciled. Its scope is state, not period: it never chooses which dates run, and it never deletes anything on its own. - `verbose_logs` boolean - `extra` object - `chainexecutionid` string, nullable: Unset for a preflight: nothing was started. - `consumers` ExecutionConsumerResult[] - `consumerid` string, required - `status` string, required - `preview_executionid` string, nullable - `warnings` ExecutionWarning[] - `code` string, required - `message` string, required - `blocking` boolean - `blocked` boolean: Only a preflight reports this: the same request sent for real would be refused. ## Other responses - `400`: Bad Request - `404`: Not Found - `409`: Conflict - `422`: Unprocessable Entity ## Changes - **2026-11-03** `020884969534`: 1 info - endpoint added [Operation history](https://skmtc.dev/chift/apis/chift-api/changes/syncs/:syncid/flows/:flowid/execute/post.md) --- [API](https://skmtc.dev/chift/apis/chift-api.md) - [All operations](https://skmtc.dev/chift/apis/chift-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chift/apis/chift-api/revisions/020884969534?raw)