API Reference

Returns the authenticated caller's bootstrap payload: identity and org membership. This is the natural first call for an agent — confirm who the API key belongs to (email, name, org role) and see the organization's member roster before building or running workflows. For accessible workflow metadata, use List Workflows.

Invites a person to your organization. They receive an email invitation and hold no access until they accept, so the roster returned by Get User is unchanged until then — a successful call has not yet given anyone access.

Check data.email_sent. The invitation is recorded whether or not the email goes out. When it is false the invitee was never told, the seat is still held, and re-inviting is refused with ALREADY_INVITED — revoke it with Remove Member and invite again.

A pending invitation still reserves a seat against your plan's member limit, so an org near its cap can be refused even though the roster itself has room.

Scope: members:write — carried only by an org admin's API key.

Removes a person from your organization. Their API keys are revoked and the credentials they shared with the org are withdrawn before the roster entry is dropped, so access dies first and nothing outlives the membership.

If the address has a pending invitation rather than a membership, the invitation is revoked instead — data.removed says which happened.

Check data.warnings. Removal is never blocked, so anything of theirs the org was relying on is affected: workflows using a connection they owned start failing, active sources they owned stop importing, and workflows they still own keep running — scheduled runs charge the owner, so the org keeps paying for them. Each warning names the affected resources so you can reassign them. An empty array means none of those checks found anything, not that the member was inconsequential.

Percent-encode the address. A literal + in a query string decodes to a space, so send sam+team@acme.com as sam%2Bteam%40acme.com.

You cannot remove yourself; another admin has to. An empty email is a 400, never a wildcard.

Scope: members:write — carried only by an org admin's API key.

Returns the caller's organization knowledge file — a single free-form text/markdown blob describing the org (who they are, what workflows they run, their goals). It's shared context an agent can read before planning work. When no file has been written yet, this returns { content: null, exists: false, updated_at: null } rather than a 404. Write it with Set Knowledge.

No scope required — any valid API key may read its own org's knowledge file.

Creates or replaces the caller's organization knowledge file — a single free-form text/markdown blob describing the org (who they are, what workflows they run, their goals). Idempotent full replacement: content becomes the entire file, so read the current value with Get Knowledge first if you intend to append. Send an empty string to clear it.

Max size: 256 KB (UTF-8).

No scope required — any valid API key may write its own org's knowledge file.

Returns all input fields currently configured for a workflow. Use this to check existing inputs before adding or updating.

Adds input fields to the workflow. Existing inputs are not affected. Returns all inputs (existing + new). Reference input fields in actions with {{input.field_name}} syntax.

The request body is a JSON array — no wrapper object needed.

Valid types: string, url, email, number.

Removes a single input field from the workflow. Any action references using {{input.field_name}} for this field will break. Check your action configurations before deleting.

Adds an action to the workflow. Returns the action_instance_id, input fields to configure, and output fields with reference strings.

Appends to the end of the chain by default. Use after to insert after a specific action. Pass name to set a custom display name on creation — otherwise the action template's default name is used. The display name can be changed later via Rename Action.

Configure in the same request. Every optional field Configure Action accepts — inputs, run_if, continue_workflow_if_action_fails, note — can be sent in this body too, with identical shapes and semantics. See Configure Action for those shapes. Doing so turns the usual add-then-configure pair into a single call, and any warnings come back on the 201 in the same warnings[] shape. If configuration fails validation outright, nothing is created.

Otherwise, add first and wire inputs afterwards with Configure Action.

ackDB actions support ingest, company/person/contact/member lookup, company/person/contact update/upsert, and company/contact relationships. The legacy ackdb_merge_record remains a company-merge alias. New ackdb_ingest actions expose boolean accepted first; company creation remains the separate entity_created output. Accepted includes retries, queued requests and retained unresolved content, and excludes dropped or failed items. It does not prove a new event was created or queued processing finished.

Configures an action instance. Send only the fields you want to set — unset fields keep their current value.

Body fields:

• inputs — map of field name → value. String values can be literals, public reference tokens ({{input.<name>}} / {{<action_instance_id>.<name>}}), or a mix. String-array values are used for waterfall-provider fields (ordered provider IDs). Environment variables are referenced the same way, as {{env.<key>}} — see List Environment Variables for the available keys.
• run_if — optional gate. AND/OR condition groups: {conditions: [{conditions: [{variable, operator, values?, combinator?}], combinator?}]} — the same shape as the filter action's path_conditions (a single condition is one group with one leaf). Pass null to clear an existing condition.
• continue_workflow_on_failure — when true, downstream actions still run for a row even if this action fails.

For action-specific configuration guidance (prompts, waterfall provider IDs, model selection), see the action detail file at /docs/action-detail/{action_id}.txt.

Supported operator values depend on the variable's stored type — the type is derived from the sheet's chain, so you don't pass it.

• Universal (any type): is, is not, is empty, is not empty. is empty / is not empty ignore values.
• String / email / url / imageUrl: contains, does not contain, starts with, does not start with, ends with, does not end with. Matching is case-insensitive.
• Number / currency: greater than, less than, greater than or equal to, less than or equal to, is between (pass [min, max]).
• Date: is after, is before, is between (pass [start, end]). Values are parsed by moment(...).
• Array / sectionList / json: contains, does not contain.

Pass values as an array of strings — number / date matchers coerce as needed.

Environment variables. Reference an org environment variable in any string value as {{env.<key>}}; Floqer substitutes its value for every row at run time. Get the available keys from List Environment Variables. Two cases come back as warnings on a 200:

• env_variable_unavailable — the variable is workflow scoped and has no value on this workflow. The reference is still saved, but rows error until a value is set for it. Pass workflow_id to List Environment Variables to see only the variables usable here.
• env_not_supported_in_conditions — an environment variable was used in run_if or a Filter action's path_conditions. Environment variables are substituted after conditions are evaluated, so one there can never resolve; that condition is skipped rather than saved.

Cache invalidation. Any change to this action's configuration — including whitespace-only edits, a new run_if predicate, or flipping continue_workflow_on_failure — invalidates the cache for every row already processed through it. That action, and every action downstream, re-runs and re-bills on the next execution. See Caching.

Sheet ID convention: to operate on the workflow's main sheet, pass the workflow's own ID as sheet_id — the main sheet's ID equals the workflow ID. For additional sheets under the workflow, pass the child sheet's ID.

ackDB: discover Source, Events, settable fields and enum choices through Get Action Field Options. Lookup type spells company entity; Update Scope spells it company. Configure field lists as [{name, value}], preserving JSON false/0. Person-only ingest ownership comes from the registered event definition, not a request toggle.

Ordinary configure/publish reconciles a missing ackdb_ingest.accepted output into live action metadata, preserving existing output UUIDs, names, order and references. A still-old live schema can also acquire it when a new worker completes with a real Accepted boolean. Read-only Get Action/Get Outputs do not upgrade ingest schemas or historical rows. An old worker lacking Accepted omits that output. Immutable shortcut versions remain unchanged: republish a new version for the expanded schema. Conflicting preexisting Accepted UUIDs fail the save instead of silently rewriting references.

Returns every node in a workflow as a flat array, ordered topologically from the input node onward.

Reading the response:

• data[0] is always the input node (action_id: "input"). It represents the workflow's input columns and has no inputs of its own — its outputs list every input field with ready-to-paste {{input.field_name}} references. If no inputs have been defined yet, outputs is [].
• data[1..] are the actions, in topological execution order from the entry action onward. If no actions have been added yet, data contains only the input node with next: [].
• Walk the chain by following each node's next array. next: [] is terminal.
• Multiple IDs in next represent a split path — today only one downstream ID is populated, but the shape accommodates future branching actions without changing.

Resolving variable references: {{X.field}} → find the node where action_instance_id === "X" → look in its outputs. This rule works uniformly for {{input.linkedin_url}} and for action outputs like {{scrape_company_linkedin_profile_1.company_name}}.

What each action node carries:

• inputs — the variable wiring you set via Configure Action. Unconfigured fields are simply absent from the map.
• outputs — the fields this action produces, each with a ready-to-paste reference string. Absent on actions with no outputs (e.g. filter).
• continue_workflow_on_failure — present only when configured via Configure Action. true lets the chain skip past this action's failure for a row.
• run_if — present only when a condition is configured via Configure Action. The action runs for a row only when the resolved variable satisfies operator against values.

Use this endpoint to inspect the full graph of a workflow before modifying individual actions. For a single action in isolation, use Get Action.

Returns a single action from a workflow. The response data is the same per-node shape emitted by Get Action Graph — use this endpoint when you only need one action and don't want to fetch the entire graph.

Round-tripping with Configure Action: the inputs map in this response matches the body Configure Action accepts. GET the current action, modify inputs, then PATCH the same URL (Configure Action) to save.

Validation warnings on read. The response includes a warnings array whenever the action's current configuration has issues (unresolved references, downstream references, required fields missing). Agents inspecting a workflow they didn't build — or revisiting one after changes upstream — can spot broken config without having to re-PATCH. Same warning shape as Configure Action's response, so one parsing path covers both.

Reserved action_instance_id values: "input" (the input pseudo-node — use List Inputs or data[0] of Get Action Graph) and "graph" (the graph endpoint path — use Get Action Graph). Both return 404 here.

Removes an action from the sheet's chain by relinking its previous and next neighbours so the chain skips it.

Returns the affected inputs. Any action whose configuration references one of the deleted action's outputs is listed in dependent_actions[], with inputs carrying only the fields that actually referenced the deleted action. Values are translated to public reference form so the broken refs are easy to spot. Unrelated fields on the same dependent action are not included. The caller is expected to fix the listed fields via Configure Action.

Cannot delete the input action — pass any other action_instance_id. Attempting to delete the input action returns 400. The reserved string IDs "input" and "graph" (the graph endpoint path) return 404.

Cache invalidation. Removing an action invalidates the cache for every row already processed through that action. The remaining chain — including all downstream actions — re-runs and re-bills on the next execution. See Caching.

Not idempotent. Deleting an action_instance_id that does not exist returns 404. Use Get Action Graph beforehand if you need to confirm presence first.

Sheet ID convention: to operate on the workflow's main sheet, pass the workflow's own ID as sheet_id — the main sheet's ID equals the workflow ID. For additional sheets under the workflow, pass the child sheet's ID.

Fetches the dropdown / dynamic option values for one of an action's input fields. Use it when configuring an action whose field expects a value from a connected integration (Salesforce objects, Instantly campaigns, HubSpot properties, etc.).

Pass the action's action_instance_id and the snake-cased field_name (both come back in Add Action's response) — the server dispatches to the matching resolver internally.

Cascading resolvers (e.g. Salesforce: pick object → pick external ID field) take their parent selection via context. Each cascading resolver declares its required context keys; calling without them returns a 400 with the list of missing keys so callers can fetch the parent first.

Returns options as { value, label, extras? }. value is what to send back via Configure Action; extras carries per-integration metadata when relevant.

ackDB: ackdb_ingest:source lists enabled source tokens. ackdb_entity_lookup:events uses context.lookup_type (entity for company, person, contact, or member), falling back to the saved literal Lookup type only when context omits it. Missing, unresolved, or invalid lookup types return 400; they never silently select company. Person options include person-only events; company options exclude them. Event coverage is data-gated, so a newly registered type may not appear until data exists. Values are source:event_type. Contact/member intentionally return no event options.

ackdb_update_record exposes company_fields_to_set, person_fields_to_set, and contact_fields_to_set, including registered attributes, core fields, supported identity keys, and company/contact owners. Optional context.scope must match the selected field catalog. Lookup type, Scope and boolean switches also expose static options; boolean option strings true/false can be configured as JSON booleans. ackdb_company_relationship exposes relationship_target, operation, and relationship_type; explicit context overrides its saved target. Relationship targets remain case-insensitive; legacy missing/empty target defaults to company. Company operations are create/end/retract/merge; contact operations are contact_create/contact_end/contact_retract. The legacy ackdb_merge_record action has no dropdown fields.

ackDB catalogs use the workflow connection's stored baseUrl/apiKey, like action execution. A missing connection returns 424; upstream failures return 502 instead of silently substituting another grain or a partial field catalog.

Returns the output schema of an action — the names, types, and reference tokens of the fields it produces, for wiring into downstream actions. This does not return the values the action has produced — for that, use List Rows.

Static vs. dynamic actions. Static-output actions (Salesforce, HubSpot, enrichment providers, etc.) have a fixed output schema — this endpoint returns it immediately, no run required. Dynamic-output actions — http_api_call, raw_to_structured_array, AI generations with custom output shapes — only know their schema after they run, and the schema returned here reflects only the latest run. There's no historical view.

Wiring implication. To reference a dynamic action's outputs from a downstream action, run it against at least one row first. The schema then populates and downstream Configure Action calls can wire {{<action_instance_id>.<field>}} into their inputs.

structured_array outputs carry per-column schemas under columns[], each with its own structured_array_reference token shaped {{<action_instance_id>.<list>.<column>}}.

For ackdb_ingest, this GET reports the stored schema without reconciling old 19-output configurations. Configure/publish or a future boolean-bearing live completion adds Accepted while preserving old UUIDs. Existing row/cell outputs are historical stored values: they are never backfilled, even when the current schema includes Accepted. The frontend may derive a legacy display from recorded Results; the public API does not invent that field. Frozen shortcut versions require republishing a new version.

Sets the display name of an action instance. Single-field PATCH — the only body field is name.

Why rename. The default name is the action's template name (e.g. Enrich Company LinkedIn Profile). That's fine for a one-off, but a workflow that uses the same action multiple times — or several similar actions side by side — ends up with ambiguous duplicates. Rename each instance to reflect the specific role it plays in the chain so collaborators reviewing the workflow, and you debugging it later, can tell the nodes apart at a glance.

Re-orders an action within the sheet's chain. Updates chain pointers on the moved action, its old neighbours, and its new neighbours; configured inputs and outputs are untouched.

Positioning. Omit after to move to the end of the chain. Pass "input" to move to the start (immediately after the synthetic input node). Otherwise pass an existing action_instance_id to move directly after that instance. after cannot equal the action being moved, and the input action itself cannot be moved.

Reference safety. Move does NOT rewrite the action's configured inputs. If the new position pushes the action ahead of an upstream reference — or pushes a downstream consumer ahead of this action — those references will fail at runtime. Fix broken refs afterwards via Configure Action.

Re-orders the provider list on a waterfall (stepDownSearch) input field. Pass the snake-cased field_name from Add Action to Workflow's inputs[] and a providers array listing every currently configured provider apiId exactly once, in the desired execution order.

This endpoint only reorders — it does not add or remove providers. To change which providers are enabled, use Configure Action.

Cache. Same as Configure Action — reordering invalidates the row-level cache for this action and every downstream action on the sheet.

Attaches a free-text note to an action instance. One note per action — calling again on the same action overwrites whatever was there. Notes come back on the action via Get Action and on each node of Get Action Graph as a note field (absent when none has been saved).

Use this to flag work-in-progress configuration, document why an action is parked, or leave context for collaborators reviewing the workflow. The note is workflow content, not a system field — it does NOT change what the action does and does NOT invalidate the row-level cache. The workflow's updated_at timestamp is bumped on save.

Sheet ID convention: to operate on the workflow's main sheet, pass the workflow's own ID as sheet_id — the main sheet's ID equals the workflow ID. For additional sheets under the workflow, pass the child sheet's ID.

Adds a new sheet to the workflow identified by workflow_id. Returns the full sheet object. Pass the returned sheet_id as the {sheet_id} path parameter on every sheet-scoped endpoint (Add Inputs, Add Action, Add Data, Run Sheet, etc.).

Routing data into the new sheet. Sheets receive rows via the send_to_sheet action on another sheet in the same workflow. On the source sheet, add send_to_sheet, set target_sheet_id to the sheet_id returned here, and map source fields to the new sheet's input columns. To expand a structured_array (one row per array item), set expand_from on the send_to_sheet action. Full configuration: /docs/action-detail/send_to_sheet.txt.

Updates a sheet's settings. Send only the fields to change — at least one of auto_run, cache_enabled, cache_since; omitted fields are left untouched.

auto_run: true (the default on every sheet) runs the action chain on each row that lands — from Add Rows, a synced source (initial backfill and live rows alike), or send_to_sheet. auto_run: false loads rows without running them; run them later with Run Rows (row_ids or first_10).

Works on the main sheet: pass sheet_id === workflow_id. The main sheet is created with the workflow and never passes through Create Sheet, so this is the only way to switch it off. Turn it off before Sync Source to Workflow when you want to load a source's rows without running them.

Applies to rows that arrive after the change; rows already on the sheet are untouched.

cache_enabled / cache_since are the same settings Create Sheet accepts: whether identical-input rows reuse cached outputs, and the earliest date (YYYY-MM-DD, UTC) a cached run may be from to count as fresh. cache_since: null clears the cutoff.

Returns the full updated sheet so the values can be verified without a follow-up Get Workflow Overview.

Sets a sheet's name. Single-field PATCH — the only body field is name (required, trimmed, non-empty).

Renaming the main sheet does NOT rename the workflow. Pass sheet_id === workflow_id to rename the main sheet's tab; the workflow's own name is left untouched, and Get Workflow Overview keeps returning it as data.name while data.sheets[0].name changes to the new label. To rename the workflow itself, use PATCH /api/v1/workflows/{workflow_id}/name (Rename Workflow).

Cache. Renaming does not affect row data, cached action runs, or the action chain — only the sheet's name. The workflow's updated_at timestamp is bumped.

Sheet ID convention: sheet IDs come from Get Workflow Overview (data.sheets[].sheet_id) or from Create Sheet. The main sheet's ID equals the workflow ID.

Permanently deletes a child sheet from the workflow. Archives the sheet and its action chain; row data and run history on the sheet are no longer reachable. Cannot be undone.

Only the sheet owner can delete a child sheet. Shared users and org members with workflow access cannot delete sheets they do not own.

The workflow's main sheet cannot be deleted (sheet_id must not equal workflow_id). To remove the entire workflow including its main sheet, use Delete Workflow.

Sheet ID convention: pass the child sheet's UUID as sheet_id — not the parent workflow ID.

Adds rows to a sheet. Each row's keys are input field names (from Add Inputs); values are written as-is — there is no type checking at the API layer, so any type mismatches surface later when downstream actions try to consume the data. Missing fields are stored as null; unknown fields come back in rejected.

Partial success — never atomic. Accepted rows are written and their UUIDs returned in row_ids — pipe directly into Run Rows's row_ids. Any rows the server rejects are echoed back in rejected with their original content and field-level error codes so you can fix and resend just those. A batch of 10,000 with 5 bad rows writes 9,995 and returns the 5 failures in rejected.

Max 1,000 rows per call.

Runs a subset of the sheet's rows through the action chain. Specify the subset in one of three ways:

• row_ids — array of specific row UUIDs (from Add Rows or List Rows). Rows not listed are untouched.
• first_10: true — shortcut for "run the first 10 rows on the sheet" (by created_at ascending). Safe experimentation default.
• filters / status_filters / created_at — every row matching them, selected on the server (the same shapes List Rows takes). Use this to run a subset — e.g. rows whose cell on an action failed — instead of listing rows to collect their IDs.

Exactly one of these must be provided. None, or more than one, returns 400. An empty filters: [] or status_filters: [] also returns 400 — omit a filter you are not using.

Asynchronous. The endpoint returns immediately after queueing. Poll List Rows for per-cell status and outputs — each cell (one action × one row) queues, runs, and bills independently.

To run every row on the sheet, use Run All Rows instead — a separate endpoint (no request body), so a misread filter can never run the whole sheet.

Prerequisites: the sheet has at least one action configured, and the rows in row_ids (if provided) already exist on the sheet.

Queues every row on the sheet for execution through the action chain. No request body required — the path is the contract.

Same async semantics as Run Rows — the endpoint returns immediately after queueing; poll List Rows for per-cell status and outputs.

⚠️ Credit cost. Scales with (rows on sheet) × (actions in chain). A sheet with 10,000 rows and 5 actions costs 50,000 cell executions. Do not call this without first running a sample (e.g. run_after_add: "first_10" on Add Rows, or Run Rows with first_10: true) and verifying outputs. See the Run a Workflow tag for the full build-loop guidance.

Separate from Run Rows (which takes row_ids or first_10) so an agent can't accidentally run the whole sheet by misinterpreting a filter. Cache-enabled cells with unchanged resolved inputs still hit cache and don't re-bill.

Runs a single action against a set of rows — useful for refreshing one action's outputs after a Configure Action edit, without re-running everything upstream of it.

By default, only the targeted action runs. Nothing downstream of it in the chain executes. To also run the rest of the chain after this action finishes, set run_next_action: true in the body.

Body:

• row_ids — array of row UUIDs (from Add Rows or List Rows). Omit or pass an empty array to queue every row on the sheet. Capped at 1000 IDs per request.
• filters / status_filters / created_at — with row_ids: [], queue only the rows matching them, selected on the server (the same shapes List Rows takes). E.g. re-run only the rows whose cell on this action failed, without listing their IDs first. Combining them with a non-empty row_ids returns 400, and so does an empty filters: [] or status_filters: [] — it never falls back to running every row.
• run_next_action — false (default) runs only the targeted action. true runs the targeted action then continues through the rest of the chain, re-running every action that comes after it. Useful after Configure Action when you want to refresh a single action and everything downstream of it in one call.

Asynchronous. Returns immediately after queueing. Poll List Rows for per-cell status and outputs — each cell (one action × one row) queues, runs, and bills independently.

Permanently deletes rows from a sheet. For each deleted row, the input values and all per-cell outputs across every action in the chain are removed. Cannot be undone.

Partial success — never atomic. Row UUIDs that exist on the sheet are deleted and returned in deleted_row_ids. Any UUIDs the server can't delete (not found on this sheet, malformed) come back in rejected with a reason. A batch of 10 with 2 bad UUIDs deletes 8 and reports 2.

Max 200 row UUIDs per call.

Permanently deletes every row on the sheet, including all input values and per-cell outputs across every action in the chain. Cannot be undone. Use with extreme caution. No request body required — the path is the contract.

When to use. Iterating on a workflow build: add 10 test rows → run → verify → delete all → add real 1,000 rows → run. Separate from Delete Rows (which targets specific row UUIDs) so an agent can't accidentally wipe a sheet by misinterpreting a filter.

Returns rows on a sheet with their inputs and per-cell action status/outputs. Use this to poll for results after Run Rows, or to inspect the current state of a sheet.

POST, not GET — passing up to 200 row UUIDs as a filter doesn't fit reliably in a query string, so the request body carries the filter and pagination.

Pass optional row_ids to filter — the typical flow after Add Rows or Run Rows when you want only the rows you just touched. Omit row_ids to browse all rows on the sheet (paginated).

Browse-mode filtering — when you omit row_ids, you can narrow the result set with filters (sheet input-column value filters), status_filters (per-action cell-status filters), and created_at (row creation time filter). These three cannot combine with row_ids — picking explicit row IDs and filtering at the same time returns 400.

Each returned row includes the inputs you provided and a cells object keyed by action_instance_id (one entry per action in the chain). For rows that haven't been run yet, cells is an empty object {}.

Each cell has a status that progresses queued → running → complete | failed. Complete cells carry their outputs inline as outputs when small, or as a pointer under outputs_ref when the payload is large (e.g. LinkedIn profile scrapes, enrichment blobs). Failed cells carry an error message. queued and running cells carry only status.

Large payloads — outputs_ref.url is an absolute Get Cell Outputs URL. GET it with your API key to read the payload; it returns the same outputs shape the cell would have carried inline, so one parser handles both cases. Those fetches draw on their own 600/minute quota rather than the general API rate limit, so following every pointer on a page leaves your normal request budget intact.

Paginated — default page size 20, max 200.

Returns the outputs of one complete cell. This is what outputs_ref.url on a List Rows cell points at — call it with your API key exactly like any other endpoint.

List Rows inlines a cell's outputs when the payload is small and hands back an outputs_ref pointing here when it is large (LinkedIn profile scrapes, enrichment blobs). The response shape is the same either way: keys are the action's output field names.

The URL never expires and carries no credential of its own — it is authorized by your API key on every call, so revoking the key revokes access.

Payload fetches are metered in their own quota (600/minute per key) rather than against the general API rate limit, so following many outputs_ref pointers from one page of rows does not exhaust your request budget.

Starts a CSV export of the sheet's rows and returns immediately with an export_id. The file is built in the background — poll Get Export until status is completed, then download file_url.

Choosing what to export. Send no body (or {}) to export the whole sheet. Name rows explicitly with row_ids, or narrow the sheet with filters / status_filters / created_at — the same shapes List Rows accepts, with the same operators, so a filter that selects a row there selects it here too.

row_ids and the filters cannot be combined — doing so returns 400. An explicit row selection takes precedence in the export engine, so a request carrying both would quietly ignore what you filtered on and hand back a file that doesn't match what you asked for. exclude_row_ids subtracts from the filtered set and is ignored when row_ids is given.

The output is always CSV — UTF-8 with a byte-order mark, one column per input field and action output, one row per sheet row. Cells that have not produced a value (queued, running, failed) are exported blank.

One export at a time. While an export of this sheet is building for you, starting another hands back the in-flight job with created: false rather than queueing a second build — so a retry is safe. Exports are private to the API key's creator: a key created by a different member of your organization cannot read them.

Zero rows is a 400, not an empty file — an export that matches nothing is nearly always a mistake in the selection, and it is cheaper to hear about it here than to poll a job to find out.

Requires the workflows:read scope.

Reports the progress of an export started by Export Sheet and, once it is finished, hands back the download link.

status is running (queued or building), completed, or failed. Poll every few seconds — there is no webhook. On failed, error says why.

file_url appears only when status is completed. It is a signed link valid for 15 minutes, minted fresh on every poll — if it expires, poll again for another. Treat it as a secret: it downloads the file without an API key for as long as it is valid, so do not log it or store it anywhere durable.

An export is readable for 24 hours, after which it is forgotten and this returns 404. Exports are private to the API key's creator, and an export_id belonging to a different sheet is not readable through that sheet's path — both answer 404.

Requires the workflows:read scope.

Creates a new empty workflow with a main sheet. Returns the workflow_id — this is also the main sheet's sheet_id (the two IDs are equal for main sheets).

Returns all workflows the caller can access, sorted by most recently updated first. Each entry carries the ID, name, and timestamps — no deeper state. Use Get Workflow Overview for sheet roster, settings, webhook URLs, and sharing on a single workflow.

Returns operational info for a single workflow — the bootstrap call after List Workflows.

Includes workflow metadata (name, timestamps), a per-sheet roster with settings (auto_run, cache), webhook URLs for pushing rows into each sheet, and sharing metadata.

data.sheets[0] is always the main sheet; child sheets follow sheets_config.sheetsOrder when set, otherwise creation order.

is_owner is true when the caller owns the workflow; shared_users is populated only for owners (other callers get []).

When to use. After List Workflows to enumerate sheet_id values, inspect cache settings, and webhook URLs before configuring send_to_sheet, lookup_another_floqer_workflow_row, or other sheet-scoped build/run endpoints.

Sets the workflow's name. Single-field PATCH — the only body field is name (required, trimmed, non-empty).

This does not rename the main sheet's tab. The workflow name and the main sheet's label are stored separately. To rename a sheet — main or child — use PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/name (Rename Sheet). Get Workflow Overview reports this name as data.name; data.sheets[0].name follows it only until the main sheet is given its own label.

Cache. Renaming does not affect sheets, rows, cached action runs, or the action chain — only the name.

Any caller with access to the workflow may rename it; unlike Delete Workflow this is not restricted to the owner.

Deep-copies a workflow's configuration — its input columns, action chains, and child sheets — into a new workflow owned by the caller in their active organization. Use it to branch a proven workflow before changing it, or to hand a team a ready-made starting point.

What comes across: the structure. Input definitions, every action with its configuration and {{ref}} wiring, and all child sheets.

What does not: data rows, run history, and sharing permissions. The copy starts empty — add rows and run it like any new workflow. Because no cells are copied, nothing is billed by this call.

Ownership and placement. The copy is owned by the caller (not the source's owner) and lands in the root folder — the public API does not expose folders.

Child sheets. If workflow_id identifies a child sheet rather than a top-level workflow, the copy stays attached to the same parent workflow rather than becoming a new top-level one.

name is required and becomes the copy's name. It is trimmed and does not need to be unique.

Permanently deletes a workflow and everything in it — all sheets, inputs, actions, rows, and run history. Cannot be undone.

Only the workflow owner can delete a workflow. Shared users and org members with workflow access cannot delete workflows they do not own.

Returns the records that would be imported for the given payload, without persisting anything. Use it to validate your selection — filters, list memberships, object types — before committing with Create Source.

The request body shape depends on source_id. The route only enforces that the body is a JSON object; per-source validation runs inside the handler and surfaces as a 400 with a specific message. The authoritative body reference for each source is /docs/source-detail/{source_id}.txt — load it before building the payload.

Results are capped at 100 rows; metadata.total_results is the full upstream count. Each row's keys depend on the source's payload (e.g. which fields you asked for). Preview never creates a source and never consumes credits.

Requires the sources:read scope.

Persists a new source and starts importing. Behavior is source-specific and driven by the body — a source may import once or keep importing over time; consult /docs/source-detail/{source_id}.txt for the exact fields.

The request body shape depends on source_id. The route only enforces that the body is a JSON object; per-source validation runs inside the handler and surfaces as a 400 with a specific message. Preview the payload first — Create accepts the same body plus the create-only fields, so a payload that previews cleanly is ready to create.

Returns source_instance_id — the new source's UUID, distinct from the source_id slug in the URL, which names the source TYPE. The initial import runs asynchronously: the call returns as soon as the source is persisted and the import is queued, not when records have finished arriving.

Requires the sources:write scope.

Resolves the dynamic option values for one of a source's payload fields — the values a field expects when they come from a connected system rather than free text. Call it while building a Preview / Create payload, then reference the returned values back in the body.

Which field_names a source supports, and whether a field's resolver needs context, is documented per source in /docs/source-detail/{source_id}.txt. Cascading resolvers (where one selection narrows the next) take the parent selection via context in the body; calling one without its required key returns a 400 listing the accepted key spellings. Resolvers without cascades accept an empty body.

Returns options as { value, label, extras? }. value is what to send back in the source's payload; label is the human-readable text; extras carries per-integration metadata when present.

Requires the sources:read scope.

Lists the sources you've created, newest first. Only sources whose type is supported by this API are returned (internal data feeds not exposed by this API are omitted).

Each entry's source_instance_id is the source INSTANCE UUID — pass it to Sync Source to Workflow (POST /api/v1/sources/{source_instance_id}/sync) to connect it to a workflow. source_id is the source-type slug used by the Preview / Create / Get Source Field Options endpoints.

Requires the sources:read scope.

Returns paginated rows that have been imported into a created source. source_instance_id is the source INSTANCE UUID returned by Create Source.

Use this to inspect or poll a source after Create while its backfill runs, or to page through the full dataset before Sync Source to Workflow. Row field names match Preview Source for that source type.

Query params page_no (1-indexed, default 1) and page_size (default 20, max 200) control pagination. When page_no * page_size > total_count, rows is []. total_count is the total number of rows stored for the source.

Requires the sources:read scope.

Connects a created source to a workflow and, by default, backfills the workflow with the source's existing rows. This is the step that wires inbound source data into a pipeline — once synced, the source's records flow in as workflow rows.

source_instance_id here is the source's UUID — the value returned by Create Source.

field_mapping maps the workflow's inputs to the source's fields. Each key is a public workflow input reference (input.<field>); each value is the source field NAME to pull — the row's top-level key exactly as it appears in the Preview Source response (e.g. Name, email, business_id), NEVER a nested path like Name.value. The import resolves each field's value automatically, including for sources whose preview cells render as {label, value}. Keys are case-sensitive — use the exact lowercase snake_case reference from List Inputs (minus the {{ }}); variants like Input.Email or input.firstName return 400, though surrounding {{ }} is tolerated.

push_existing (default true) toggles the backfill — set it false to connect the source without importing its current rows.

Whether landed rows run is the sheet's auto_run toggle, not a sync option — it governs backfilled and future rows alike. To load without running, set auto_run: false with Update Sheet (PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}) before syncing, then run chosen rows with Run Rows. Leave it on to auto-run every row that arrives.

run is deprecated. It is accepted, ignored, and reported in warnings[]; it will be rejected in a future release.

Pauses or resumes a created source. source_instance_id is the source INSTANCE UUID returned by Create Source.

Set status to paused to stop an ongoing source's recurring runs, or active to resume it. Pausing stops the schedule (when present), disables provider webhooks where applicable (e.g. Stripe, TheirStack), and prevents further imports; resuming restarts them. Static / one-time sources have nothing recurring to pause, but the status still updates.

Requires the sources:write scope.

Create a durable sync from an ackDB segment into a published Floq workflow. New segment members are delivered every five minutes. field_mapping keys are public workflow input references from List Inputs; values are ackDB segment field names. Defaults are conservative: existing members are not pushed, delivered rows are inserted without running the workflow, and re-entries are suppressed.

Read the durable sync for one ackDB segment, including destination connections, delivery counters, current lifecycle state, breaker/error details, and a best-effort live segment size. An unsynced or inaccessible segment returns synced: false.

List the organization's durable ackDB segment-to-Floq syncs, newest first. This stored-state list does not call ackDB for a live segment count; use Get Sync for that detail. A key restricted by allowed_workflow_ids sees only permitted destinations.

Resolve a sync breaker in pending_confirmation: push releases held members for delivery, while skip records them as skipped. A workflow-restricted key must cover every destination on the sync.

Resume a sync watcher that auto-paused after an import error. This clears the surfaced error and restarts its scheduler. Breaker-held syncs use Confirm instead. A workflow-restricted key must cover every destination.

Stop the segment sync, archive every destination connection, and remove its scheduler. Rows already delivered to workflows remain. A workflow-restricted key must cover every destination.

Update one sync destination. field_mapping replaces the mapping for future deliveries; existing workflow rows are not re-pushed. status: paused holds new members until Resume chooses whether to deliver or skip the backlog.

Resume a paused destination and choose what happens to members accumulated while paused: deliver queues them, while skip records them as skipped.

Archive one destination connection. Other workflows on the same segment sync continue receiving members, and rows already delivered to this workflow remain.

Packages a workflow as a shortcut and publishes its first version, in one call. You say what it returns; what it takes is read from the workflow:

• input_schema — the workflow's input columns (List Inputs). Every column becomes an input; its reference is the snake_cased column name. Nothing to send.
• output_schema — the outputs you send, in order. Each item names one field a run returns and points it at a value: a {{input.<field>}} or {{<action_instance_id>.<field>}} reference, a literal, or a mix — the same syntax Configure Action takes. Create Shortcut writes them onto the workflow's output_shortcut action itself, adding one to the end of the chain when there is none, so do not add or configure that action first.

A value that references a field nothing produces is kept and reported in warnings on the 201 — it will never resolve at run time.

Requirements (a 400 with code SHORTCUT_WORKFLOW_INELIGIBLE lists every unmet one in reasons): the workflow has at least one named input column. You must be able to edit the workflow (403 otherwise). A workflow that already has one output_shortcut action per branch cannot be packaged here (400); use the Floqer app. A refused call changes nothing on the workflow.

One shortcut per workflow: a second call returns 409 SHORTCUT_ALREADY_EXISTS. The created shortcut is published and runnable immediately — pass its id to Run Shortcut.

Requires the shortcuts:write scope.

Returns every shortcut the caller can access — the same set the Floqer app shows: shortcuts they created (master), and shortcuts shared with them or published to the whole organization (shared). Each entry carries the shortcut's full input_schema and output_schema, so a single List Shortcuts call is enough to discover what's runnable and what each shortcut takes and returns.

Only published shortcuts (is_published: true) can be run — see Run Shortcut.

Use search to find a shortcut by name. Shortcuts with callable: true can also be called from inside a workflow: add the call_shortcut action and set its shortcut input to the shortcut's id.

Requires the shortcuts:read scope.

Returns full details for a single shortcut. This is the bootstrap call before running one:

• input_schema — the fields the shortcut takes. Each field's reference (snake_case, e.g. linkedin_url) is the key to use in input_data when calling Run Shortcut. Check required and defaultValue to know what you must send.
• output_schema — the fields the shortcut produces. Each field's name (e.g. Company Website) is the key under which its value appears in a run's output_data.
• is_published — only published shortcuts can be run; running an unpublished shortcut returns 403.

Requires the shortcuts:read scope.

Changes a shortcut you created. Send only the fields you want to change.

• name, description, icon_emoji — metadata, applied immediately.
• outputs — the full list of fields a run returns, in the same shape Create Shortcut takes. It replaces the previous outputs, is written onto the workflow's output_shortcut action, and publishes a new version of the shortcut. The version is re-derived from the workflow, so input columns added since the last publish are picked up at the same time; every existing input keeps its type, required flag and default. An output whose name is unchanged keeps its identity. To pick up new inputs without changing outputs, send the current outputs again.

A refused call changes nothing — not the workflow, not the shortcut. Unknown body keys are rejected with 400.

A shortcut is frozen at publish. Runs execute the latest version's frozen graph and Get Shortcut / Get Shortcut Run read the stored schemas, so editing the workflow on its own (Configure Action, Add Inputs) never changes what the shortcut takes or returns. This is the call that does.

Removing an output that another workflow's Call Shortcut cell reads is refused with 409 SHORTCUT_CONTRACT_BREAK and the list of callers; send force: true to publish anyway and mark those call sites broken.

Runs already in flight finish on the version they started on.

Requires the shortcuts:write scope.

Starts one run of a published shortcut with the provided input. Execution is asynchronous — the call returns 201 immediately with a run id; poll Get Shortcut Run until the status is terminal, then read output_data.

Body: input_data is an object keyed by each field's reference from the shortcut's input_schema (see Get Shortcut). Unknown keys are rejected with a 400 that lists the valid references. Missing fields fall back to the shortcut's input defaultValues, then to "".

The shortcut must be published — running an unpublished shortcut returns 403.

Requires the shortcuts:run scope.

Starts one run per input row, grouped under a single batch_id. Accepts up to 1,000 rows per request.

Validation is all-or-nothing: one unknown key in any row rejects the entire batch — the 400 names the offending row index. No partial batches are created.

Each row is an object keyed by field reference values from the shortcut's input_schema (see Get Shortcut). Runs execute asynchronously — follow the batch via List Shortcut Runs with ?batch_id=... until every run reaches a terminal status.

The shortcut must be published — running an unpublished shortcut returns 403.

Requires the shortcuts:run scope.

Returns a shortcut's runs, newest first, with limit/offset pagination (default 50 per page, max 100).

Filters: batch_id narrows to the runs created by one Run Shortcut Batch call; mode narrows to single (runs from Run Shortcut) or batch.

⚠ For filtered queries (batch_id or mode), pagination.total reflects the returned page's row count, not the full filtered count — paginate until a page returns fewer rows than limit.

Requires the shortcuts:read scope.

The polling target after Run Shortcut. Returns a single run with its input_data, output_data, and current status. For in-progress runs the status is recomputed live from the workflow engine, so the response reflects real-time progress.

Poll until status is terminal: completed, failed, error, or outOfCredits. In-progress values include pending and inProgress.

Reading results: output_data is null until the run finishes, then an object keyed by each output field's name from the shortcut's output_schema. Each entry carries its own per-field status — a run can complete with some fields failed (e.g. "No data found"); check per-field status before trusting a value.

Requires the shortcuts:read scope.