API Reference

The Floqer Public API is organized around REST. All requests use Bearer token authentication and return JSON responses.

Base URL: https://api.floqer.com/api/v1

OpenAPI spec llms-full.txt concepts.txt action-catalog.txt action-detail/source-catalog.txt source-detail/use-case-catalog.txt use-case-detail/

Authentication

Every Floqer API request is authenticated with a Bearer token. Your API key starts with floq_ and grants full access to all endpoints.

Get your API key

Generate an API key from the Floqer dashboard under Settings. Each key has full access to your organization's workflows, actions, and apps.

Bearer tokens

Pass your API key in the Authorization header on every request.

request header

Authorization: Bearer floq_YOUR_API_KEY

Your first request

List all workflows in your organization. If the request succeeds, the response envelope contains a data array.

curl

curl "https://api.floqer.com/api/v1/workflows/" \
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Security reminders

Never embed API keys in client-side code. Keys belong in server-side environment variables.
Rotate keys if you suspect a leak. Old keys can be revoked from the dashboard.

Rate Limits

The Floqer Public API allows 200 requests per minute and 10,000 per day per API key. Every response includes rate limit headers, and 429s tell you exactly how long to back off.

Default limits

200

requests / minute

10,000

requests / day

Limits are per API key. Contact support for higher limits.

If you hit the limit

The API returns a 429 with a retryAfter field — the number of seconds to wait before retrying.

429 response

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42
}

Errors

Every Floqer API response uses a consistent envelope. Success responses wrap data, error responses explain what went wrong.

Response envelope

All 2xx responses wrap the payload in a data field:

success envelope

{
  "status": 200,
  "data": { ... }
}

Single-issue errors (401, 403, 404, 429, 500) use a flat envelope:

single error

{
  "status": 401,
  "error": "Unauthorized",
  "message": "API key is required"
}

Validation errors (400) return all field-level problems at once so you can fix them in a single retry:

validation error

{
  "status": 400,
  "error": "Validation Error",
  "message": "2 validation errors",
  "errors": [
    { "field": "name", "message": "required" },
    { "field": "inputs[0].type", "message": "must be one of: string, url, email, number" }
  ]
}

Examples you will hit

POST /workflows with empty body

400

{
  "status": 400,
  "error": "Validation Error",
  "message": "1 validation error",
  "errors": [
    { "field": "name", "message": "required" }
  ]
}

PUT /workflows/:id/inputs with an invalid type

400

{
  "status": 400,
  "error": "Validation Error",
  "message": "1 validation error",
  "errors": [
    { "field": "inputs[0].type", "message": "must be one of: string, url, email, number" }
  ]
}

Any request without an Authorization header

401

{
  "status": 401,
  "error": "Unauthorized",
  "message": "API key is required. Pass it as: Authorization: Bearer floq_..."
}

GET /workflows/:id with a non-existent ID

404

{
  "status": 404,
  "error": "Not Found",
  "message": "Workflow not found"
}

Exceeding 200 requests/minute

429

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42
}

User

Caller identity and org context — the bootstrap call for an agent. GET /api/v1/user returns who the API key belongs to (email, name, org role) and the organization's member roster. Call this first to confirm identity before building or running workflows.

Org knowledge. GET /api/v1/user/knowledge reads, and PUT /api/v1/user/knowledge writes, a single free-form text/markdown file describing the org (who they are, what workflows they run, their goals) — shared context an agent can read before planning and update as it learns. The write is an idempotent full replacement.

Get User

get/api/v1/user/

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.

Requires API key. Authentication ↑

Response

statusinteger

dataobject

Caller bootstrap payload. Identity and org membership are always present. Use List Workflows for accessible workflow metadata.

emailemail

Caller's email address (Floqer username).

first_namestring

Caller's first name from their Floqer profile. null if unset.

last_namestring

Caller's last name from their Floqer profile. null if unset.

rolestring

Organization role: admin (org lead) or member.

org_idstring

UUID of the caller's organization.

org_membersobject

Members of the caller's organization. Emails are Floqer usernames.

countinteger

Number of members in the organization.

emailsarray

Email address of each org member (Floqer username), sorted alphabetically.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/user/"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "email": "ada@acme.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "role": "admin",
    "org_id": "7c3e5b2a-9f10-4d23-8b71-1a2b3c4d5e6f",
    "org_members": {
      "count": 3,
      "emails": [
        "ada@acme.com",
        "grace@acme.com",
        "linus@acme.com"
      ]
    }
  }
}

Get Org Knowledge

get/api/v1/user/knowledge

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 Org Knowledge.

Requires the sources:read scope.

Requires API key. Authentication ↑

Response

statusinteger

dataobject

The caller's organization knowledge file: a free-form text/markdown blob describing the org. exists is false and content is null when none has been written yet.

contentstring

The file's text content. null when no file has been written yet.

existsboolean

Whether a knowledge file currently exists for the org.

updated_atdate-time

ISO 8601 timestamp of the last write, or null when unset.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/user/knowledge"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "content": "# Floqer\n\nGTM automation platform. Our team runs enrichment + outreach workflows: enrich inbound signups, find work emails via waterfall, and sync qualified leads to HubSpot. Goal: cut manual research time and keep the CRM enriched.",
    "exists": true,
    "updated_at": "2026-05-29T11:30:00Z"
  }
}

Set Org Knowledge

put/api/v1/user/knowledge

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 Org Knowledge first if you intend to append. Send an empty string to clear it.

Max size: 256 KB (UTF-8).

Requires the sources:write scope.

Requires API key. Authentication ↑

Request body

contentstringrequired

The full text/markdown content of the knowledge file. Replaces any existing content. Send an empty string to clear it.

Response

statusinteger

dataobject

contentstring

The file's text content after the write.

existsboolean

Whether a knowledge file currently exists for the org.

updated_atdate-time

ISO 8601 timestamp of this write.

Requestcurl

curl -X PUT "https://api.floqer.com/api/v1/user/knowledge"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "content": "# Floqer\n\nGTM automation platform. Our team runs enrichment + outreach workflows: enrich inbound signups, find work emails via waterfall, and sync qualified leads to HubSpot. Goal: cut manual research time and keep the CRM enriched."
}'

Response200

{
  "status": 200,
  "data": {
    "content": "# Floqer\n\nGTM automation platform. Our team runs enrichment + outreach workflows: enrich inbound signups, find work emails via waterfall, and sync qualified leads to HubSpot. Goal: cut manual research time and keep the CRM enriched.",
    "exists": true,
    "updated_at": "2026-05-29T11:30:00Z"
  }
}

Build a Workflow

A workflow is a sheet. When you create a workflow, the first sheet is created for you. All endpoints operate on sheets — configure inputs, add actions, add data, run. If you need additional sheets (e.g. to expand an array of employees into individual rows), create them with Create Sheet. Each sheet gets its own ID and works with the same endpoints.

The typical build flow: create a workflow → define input columns → add actions → configure each action's inputs by wiring variable references from upstream outputs.

Discovering available actions: there is no API endpoint that lists or describes action templates. The static catalog files are the authoritative reference:

/docs/action-catalog.txt — every action with needs, produces, category, credits
/docs/action-detail/{action_id}.txt — per-action configuration guide (model selection, prompting patterns, when to use / when not to use)

Load these once into your context before constructing a workflow. Use action_id from the catalog in the Add Action endpoint.

Inputs

3 endpoints

Each input field has a type that helps agents match fields to action inputs. When configuring an action, reference an input with {{input.name}} — for example, {{input.linkedin_url}}.

Type	Meaning	Example value
string	General text	"Floqer Inc"
url	A URL — actions that need URLs match against this type	"https://linkedin.com/company/floqer"
email	An email address	"hello@floqer.com"
number	A numeric value	42

List Inputs

get/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/inputs

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

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Response

statusinteger

dataarray

namestring

typestring

descriptionstring

referencestring

Copy this into action configuration to reference this field

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/inputs"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": [
    {
      "name": "linkedin_url",
      "type": "url",
      "description": "LinkedIn company profile URL",
      "reference": "{{input.linkedin_url}}"
    },
    {
      "name": "email",
      "type": "email",
      "description": "",
      "reference": "{{input.email}}"
    }
  ]
}

Add Inputs

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/inputs

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request bodyarray of objects

namestringrequired

Field name — used as the column header and the key when adding data rows

typestringrequired

Data type. Helps agents match fields to action inputs (e.g. an action that needs a URL can search for type url). One of: string, url, email, number

descriptionstringoptional

Human-readable description of what this field contains

Response

statusinteger

dataarray

namestring

typestring

descriptionstring

referencestring

Copy this into action configuration to reference this field

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/inputs"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '[
  {
    "name": "linkedin_url",
    "type": "url",
    "description": "LinkedIn company profile URL"
  },
  {
    "name": "email",
    "type": "email"
  },
  {
    "name": "company_name",
    "type": "string",
    "description": "Target company name"
  }
]'

Response200

{
  "status": 200,
  "data": [
    {
      "name": "linkedin_url",
      "type": "url",
      "description": "LinkedIn company profile URL",
      "reference": "{{input.linkedin_url}}"
    },
    {
      "name": "email",
      "type": "email",
      "description": "",
      "reference": "{{input.email}}"
    },
    {
      "name": "company_name",
      "type": "string",
      "description": "Target company name",
      "reference": "{{input.company_name}}"
    }
  ]
}

Delete Input

delete/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/inputs/{field_name}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

field_namerequired

The `name` of the input field (e.g. `email`). Use List Inputs to see all field names.

Response

statusinteger

dataarray

namestring

typestring

descriptionstring

referencestring

Copy this into action configuration to reference this field

Requestcurl

curl -X DELETE "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/inputs/:field_name"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": [
    {
      "name": "email",
      "type": "email",
      "description": "",
      "reference": "{{input.email}}"
    }
  ]
}

Actions

11 endpoints

Browse the action catalog to find the right action for your data. Each action lists what it needs and what it produces — match your available data types to find compatible actions.

action-catalog.txt — full action catalog

Add Action to Workflow

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/add

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.

After adding, use Configure Action to wire input variables.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request body

action_idstringrequired

Action template identifier from the action catalog (e.g. scrape_company_linkedin_profile)

afterstringoptional

Insert after this action_instance_id. Omit to append to the end of the chain.

namestringoptional

Optional display name for the new action instance. Omit to use the action template's default name. Whitespace-only values are ignored. Can also be changed later via Rename Action.

Response

statusinteger

dataobject

action_instance_idstring

Unique instance ID. Reference outputs with {{action_instance_id.field_name}}

action_idstring

Action template identifier

display_namestring

Human-readable name

inputsarray

Fields that need to be configured. Wire each one with a variable reference or static value using Configure Action.

namestring

typestring

requiredboolean

descriptionstring

outputsarray

Fields this action will produce. Use the reference string in downstream action configuration.

namestring

typestring

One of: string, url, email, number, raw_array, structured_array

referencestring

Copy this into downstream action configuration

fieldsarray

Sub-fields for structured_array types — these become input columns when expanded to a sheet

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/add"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "action_id": "scrape_company_linkedin_profile",
  "after": "scrape_company_linkedin_profile_1",
  "name": "Enrich primary contact"
}'

Response201

{
  "status": 201,
  "data": {
    "action_instance_id": "scrape_person_linkedin_profile_1",
    "action_id": "scrape_person_linkedin_profile",
    "display_name": "Scrape Person LinkedIn Profile",
    "inputs": [
      {
        "name": "linkedin_url",
        "type": "url",
        "required": true,
        "description": "LinkedIn profile URL of the person"
      }
    ],
    "outputs": [
      {
        "name": "full_name",
        "type": "string",
        "reference": "{{scrape_person_linkedin_profile_1.full_name}}"
      },
      {
        "name": "headline",
        "type": "string",
        "reference": "{{scrape_person_linkedin_profile_1.headline}}"
      },
      {
        "name": "current_company",
        "type": "string",
        "reference": "{{scrape_person_linkedin_profile_1.current_company}}"
      },
      {
        "name": "current_company_domain",
        "type": "url",
        "reference": "{{scrape_person_linkedin_profile_1.current_company_domain}}"
      },
      {
        "name": "experiences",
        "type": "raw_array",
        "reference": "{{scrape_person_linkedin_profile_1.experiences}}",
        "description": "Work history as JSON. Each item: title, company, start_date, end_date, summary, url, company_domain, company_identifier"
      },
      {
        "name": "education",
        "type": "raw_array",
        "reference": "{{scrape_person_linkedin_profile_1.education}}",
        "description": "Education history as JSON. Each item: school, degree, field, start_date, end_date"
      }
    ]
  }
}

Configure Action

patch/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}

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).
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.

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID (e.g. scrape_company_linkedin_profile_1). Returned by Add Action to Workflow.

Request body

inputsobjectoptional

Map of field name → value. Send only the fields you want to set.

run_ifobject | nulloptional

Optional gate deciding whether this action runs for a given row. conditions is an array of AND/OR condition groups — the same shape as the filter action's path_conditions. The outer array is groups, joined by each group's combinator (AND/OR); each group's conditions are leaf conditions, joined by each leaf's combinator. The first group's and first leaf's combinator is ignored. A single condition is just one group with one leaf. Pass null to clear an existing condition; omit to leave it unchanged. See the operator reference in the description above.

continue_workflow_on_failurebooleanoptional

When true, downstream actions still run for a row even if this action fails. When false (default), the row stops at this action on failure and downstream cells stay queued.

Response

statusinteger

warningsarray

Read this first. Issues that won't block saving but may cause problems at runtime. Each warning has a field, a machine-readable code, and a human-readable message. Common codes: unknown_field, unresolved_reference, downstream_reference, required_field_missing, deprecated_format (the request used a deprecated-but-still-accepted shape, e.g. the legacy flat run_if form — migrate to the documented shape).

fieldstring

Field name the warning applies to

codestring

Machine-readable warning category

messagestring

Human-readable explanation, sometimes with suggestions

dataobject

action_instance_idstring

Examples

Wire variables to fields

Variable references, static text, or mixed.

{
  "inputs": {
    "linkedin_url": "{{input.linkedin_url}}",
    "prompt": "Research {{input.company_name}} at {{scrape_company_linkedin_profile_1.website}}"
  }
}

Waterfall fields

Array of provider IDs in priority order. The first provider is tried first, then the next as fallback. Omit a provider to skip it.

{
  "inputs": {
    "waterfall_providers": ["provider_a", "provider_b"]
  }
}

Run only when conditions match

Skip this action for rows that don't match the predicate. The action's outputs resolve to empty (`""`) for downstream references. Default behavior on skip: the row stops at this action. To keep downstream running on skip or failure, set `continue_workflow_on_failure: true`.

{
  "inputs": {
    "linkedin_url": "{{input.linkedin_url}}"
  },
  "run_if": {
    "conditions": [
      {
        "conditions": [
          { "variable": "{{input.country}}", "operator": "is", "values": ["US", "CA"] }
        ]
      }
    ]
  }
}

Combine conditions with AND / OR

Each group's leaf `conditions` are joined by each leaf's `combinator`; multiple groups are joined by each group's `combinator`. The first group's and first leaf's `combinator` is ignored. Operator strings depend on the variable's stored type — numeric uses `greater than`, `less than`, `is between`; universal operators `is empty` / `is not empty` ignore the `values` array.

{
  "inputs": { "prompt": "Summarize {{scrape_company_linkedin_profile_1.about}}" },
  "run_if": {
    "conditions": [
      {
        "conditions": [
          { "variable": "{{scrape_company_linkedin_profile_1.employee_count}}", "operator": "greater than", "values": ["100"] },
          { "variable": "{{input.country}}", "operator": "is", "values": ["US"], "combinator": "AND" }
        ]
      }
    ]
  }
}

Clear an existing condition

Pass `null` to remove a previously set `run_if`. Omitting the field instead leaves the existing condition unchanged.

{
  "run_if": null
}

Non-blocking action — continue on failure

For enrichment that's nice-to-have but not required. The row keeps moving through the chain even if this action errors.

{
  "inputs": { "linkedin_url": "{{input.linkedin_url}}" },
  "continue_workflow_on_failure": true
}

Requestcurl

curl -X PATCH "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "inputs": {
    "prompt": "Write a personalized cold email to {{scrape_person_linkedin_profile_1.full_name}} who works at {{scrape_company_linkedin_profile_1.company_name}} as {{scrape_person_linkedin_profile_1.headline}}. Keep it under 100 words.",
    "model": "claude_4_sonnet"
  },
  "run_if": {
    "conditions": [
      {
        "conditions": [
          {
            "variable": "{{input.country}}",
            "operator": "is",
            "values": [
              "US",
              "CA"
            ]
          }
        ]
      }
    ],
    "continue_workflow_if_run_condition_not_met": false
  },
  "continue_workflow_on_failure": false
}'

Response200

{
  "status": 200,
  "warnings": [
    {
      "field": "model",
      "code": "unknown_field",
      "message": "Field 'model' is not recognized by this action and was ignored."
    },
    {
      "field": "prompt",
      "code": "unresolved_reference",
      "message": "Reference {{input.linkdin_url}} does not match any input field. Did you mean {{input.linkedin_url}}?"
    }
  ],
  "data": {
    "action_instance_id": "ai_generate_content_1"
  }
}

Get Action Graph

get/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/graph

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Response

statusinteger

dataarray

Nodes in topological execution order. data[0] is the input node (action_id: "input"). data[1..] are actions in execution order.

action_instance_idstring

Unique instance ID for this node. "input" for the input node; for actions, the template name suffixed with _1, _2, etc. (e.g. scrape_company_linkedin_profile_1). Used in variable references and when calling Configure Action.

action_idstring

Template identifier from the action catalog (e.g. scrape_company_linkedin_profile). The reserved value "input" marks the input node.

display_namestring

Human-readable action name.

inputsobject

Map of field name → configured value. Values are variable references (e.g. {{input.linkedin_url}}), static strings, or mixed. Unconfigured fields are absent. Empty map {} means the action has not been configured yet. Absent entirely on the input node — the input node consumes nothing upstream.

outputsarray

Fields this node produces. For the input node, this lists every workflow input column. For actions, the fields the action produces when it runs. Absent on actions that produce no fields (e.g. filter).

namestring

typestring

referencestring

Ready-to-paste variable reference for downstream actions.

continue_workflow_on_failureboolean

When true, downstream actions still run for a row even if this action fails. Mirrors the value set via Configure Action's continue_workflow_on_failure. Absent when the action has never had it configured.

run_ifobject

Conditional gate that decides whether this action runs for a given row. Always returned in the nested {conditions: [groups]} form — the same shape Configure Action accepts (a single condition is one group with one leaf). Absent when no condition is configured.

conditionsarray

AND/OR condition groups. Outer array = groups (joined by each group's combinator); each group's conditions = leaf conditions (joined by each leaf's combinator). The first group's and first leaf's combinator is ignored.

conditionsarray

variablestring

operatorstring

valuesarray

combinatorstring

continue_workflow_if_run_condition_not_metboolean

When true, downstream actions still run for a row even when this action's condition isn't met (the action itself is skipped). When false (default), the row stops at this action when the condition isn't met.

nextarray

IDs of immediate downstream actions. [] marks a terminal action. Multiple IDs represent a split path — the shape is ready for future branching actions; today this will contain zero or one entry.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/graph"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": [
    {
      "action_instance_id": "input",
      "action_id": "input",
      "display_name": "Inputs",
      "outputs": [
        {
          "name": "linkedin_url",
          "type": "url",
          "reference": "{{input.linkedin_url}}"
        },
        {
          "name": "company_name",
          "type": "string",
          "reference": "{{input.company_name}}"
        }
      ],
      "next": [
        "scrape_company_linkedin_profile_1"
      ]
    },
    {
      "action_instance_id": "scrape_company_linkedin_profile_1",
      "action_id": "scrape_company_linkedin_profile",
      "display_name": "Scrape Company LinkedIn Profile",
      "inputs": {
        "linkedin_url": "{{input.linkedin_url}}"
      },
      "outputs": [
        {
          "name": "company_name",
          "type": "string",
          "reference": "{{scrape_company_linkedin_profile_1.company_name}}"
        },
        {
          "name": "industry",
          "type": "string",
          "reference": "{{scrape_company_linkedin_profile_1.industry}}"
        },
        {
          "name": "employee_count",
          "type": "number",
          "reference": "{{scrape_company_linkedin_profile_1.employee_count}}"
        }
      ],
      "run_if": {
        "conditions": [
          {
            "conditions": [
              {
                "variable": "{{input.country}}",
                "operator": "is",
                "values": [
                  "US",
                  "CA"
                ]
              }
            ]
          }
        ],
        "continue_workflow_if_run_condition_not_met": false
      },
      "continue_workflow_on_failure": false,
      "next": [
        "filter_1"
      ]
    },
    {
      "action_instance_id": "filter_1",
      "action_id": "filter",
      "display_name": "Filter",
      "inputs": {
        "condition": "{{scrape_company_linkedin_profile_1.employee_count}} > 100"
      },
      "next": [
        "ai_generate_content_1"
      ]
    },
    {
      "action_instance_id": "ai_generate_content_1",
      "action_id": "ai_generate_content",
      "display_name": "AI Generate Content",
      "inputs": {
        "prompt": "Write a cold email to {{scrape_company_linkedin_profile_1.company_name}} about {{scrape_company_linkedin_profile_1.industry}}.",
        "model": "claude_4_sonnet"
      },
      "outputs": [
        {
          "name": "generated_content",
          "type": "string",
          "reference": "{{ai_generate_content_1.generated_content}}"
        }
      ],
      "next": []
    }
  ]
}

Get Action

get/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID (e.g. `scrape_company_linkedin_profile_1`). Returned by Add Action to Workflow, or found in the Get Action Graph response. Reserved values: `"input"` (input pseudo-node) and `"graph"` (the graph endpoint path) — both return 404 here.

Response

statusinteger

warningsarray

Validation issues with the action's current configuration, detected at read time. Absent or empty when there are no issues. Same shape and code values as the warnings returned by Configure Action — common codes: unresolved_reference, downstream_reference, required_field_missing, unknown_field.

fieldstring

Field name the warning applies to.

codestring

Machine-readable warning category.

messagestring

Human-readable explanation, sometimes with suggestions.

dataobject

The action node. Same shape as nodes in the data array returned by Get Action Graph.

action_instance_idstring

Unique instance ID for this action (e.g. scrape_company_linkedin_profile_1). Used in variable references and when calling Configure Action.

action_idstring

Template identifier from the action catalog (e.g. scrape_company_linkedin_profile).

display_namestring

Human-readable action name.

inputsobject

outputsarray

Fields this action produces, each with a ready-to-paste reference string for downstream actions. Absent on actions that produce no fields (e.g. filter).

namestring

typestring

referencestring

Ready-to-paste variable reference for downstream actions.

continue_workflow_on_failureboolean

run_ifobject

conditionsarray

variablestring

operatorstring

valuesarray

combinatorstring

continue_workflow_if_run_condition_not_metboolean

nextarray

IDs of immediate downstream actions. [] marks a terminal action. Multiple IDs represent a split path — today this will contain zero or one entry.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "warnings": [
    {
      "field": "linkedin_url",
      "code": "unresolved_reference",
      "message": "Reference {{input.linkdin_url}} does not match any input field. Did you mean {{input.linkedin_url}}?"
    }
  ],
  "data": {
    "action_instance_id": "scrape_company_linkedin_profile_1",
    "action_id": "scrape_company_linkedin_profile",
    "display_name": "Scrape Company LinkedIn Profile",
    "inputs": {
      "linkedin_url": "{{input.linkdin_url}}"
    },
    "outputs": [
      {
        "name": "company_name",
        "type": "string",
        "reference": "{{scrape_company_linkedin_profile_1.company_name}}"
      },
      {
        "name": "industry",
        "type": "string",
        "reference": "{{scrape_company_linkedin_profile_1.industry}}"
      },
      {
        "name": "employee_count",
        "type": "number",
        "reference": "{{scrape_company_linkedin_profile_1.employee_count}}"
      }
    ],
    "run_if": {
      "conditions": [
        {
          "conditions": [
            {
              "variable": "{{input.country}}",
              "operator": "is",
              "values": [
                "US",
                "CA"
              ]
            }
          ]
        }
      ],
      "continue_workflow_if_run_condition_not_met": false
    },
    "continue_workflow_on_failure": false,
    "next": [
      "filter_1"
    ]
  }
}

Delete Action

delete/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID to delete (e.g. `scrape_company_linkedin_profile_1`). Returned by Add Action to Workflow, or found in the Get Action Graph response.

Response

statusinteger

dataobject

deletedboolean

Always true on a 200 response — the action was removed from the chain.

action_instance_idstring

Echoes the action instance that was deleted.

dependent_actionsarray

Actions whose configuration referenced one of the deleted action's outputs. Empty when nothing depended on it. Each entry carries only the affected fields — keys are the dependent action's input field names (snake-cased), values are the stored inputString translated to public reference form so the broken refs are obvious. The caller is expected to re-wire these via Configure Action.

action_instance_idstring

The dependent action's instance ID.

inputsobject

Map of <snake_field_name> → input value (string). Only fields that referenced the deleted action are included; unrelated fields on the same action are omitted.

Requestcurl

curl -X DELETE "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "deleted": true,
    "action_instance_id": "scrape_company_linkedin_profile_1",
    "dependent_actions": [
      {
        "action_instance_id": "ai_generate_content_1",
        "inputs": {
          "prompt": "Write a cold email to {{scrape_company_linkedin_profile_1.company_name}} about {{scrape_company_linkedin_profile_1.industry}}."
        }
      }
    ]
  }
}

Get Action Field Options

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/{field_name}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID whose field needs options. Returned by **Add Action**, **Get Action**, or **Get Action Graph**.

field_namerequired

Snake-cased input field name from the action's `inputs[]` (matches what **Add Action** returns and what **Configure Action** accepts).

Request body

contextobjectoptional

Optional context for cascading resolvers. Keys are snake-cased and match the parent field's public name. Calling without a required key returns 400 listing the accepted spellings.

Response

statusinteger

dataobject

optionsarray

Available option values for the requested field.

valuestring

The value to send back via Configure Action.

labelstring

Human-readable label for the option.

extrasobject

Per-integration metadata. Shape varies by integration — use it for richer rendering when needed.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/options/:field_name"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "context": {
    "salesforce_object": "Account"
  }
}'

Response200

{
  "status": 200,
  "data": {
    "options": [
      {
        "value": "Account",
        "label": "Account"
      },
      {
        "value": "Contact",
        "label": "Contact"
      },
      {
        "value": "Lead",
        "label": "Lead"
      }
    ]
  }
}

Get Action Output Schema

get/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/outputs

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>}}.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance whose output schema to return. Returned by **Add Action**, **Get Action**, or **Get Action Graph**.

Response

statusinteger

dataobject

action_instance_idstring

Echo of the path parameter, for response-level self-description.

outputsarray

Fields this action produces, each with a ready-to-paste reference token for downstream wiring. Empty array for actions that produce no fields (e.g. filter), or for dynamic-output actions that haven't run yet.

namestring

Output field identifier (snake_case).

typestring

Output data type (e.g. string, url, number, raw_array, json, structured_array). structured_array is a list of structured rows; per-row schema is exposed via columns.

referencestring

Variable reference token. Drop verbatim into any downstream action's input via Configure Action to pull this output's value at run time. Shape: {{<action_instance_id>.<name>}}. For an individual column of a structured_array, use the 3-segment form {{<action_instance_id>.<list>.<column>}} (also exposed on each entry of columns[].structured_array_reference).

descriptionstring

Human-readable description of this output.

columnsarray

Present only on structured_array outputs. One entry per column, each with its own structured_array_reference token. Empty / absent for outputs whose columns aren't yet configured (e.g. a freshly added raw_to_structured_array action that hasn't run).

namestring

Column identifier (snake_case).

typestring

Column data type.

structured_array_referencestring

3-segment reference token for this column inside the parent structured_array. Shape: {{<action_instance_id>.<list>.<column>}}.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/outputs"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 0,
  "data": {
    "action_instance_id": "string",
    "outputs": [
      {
        "name": "full_name",
        "type": "string",
        "reference": "{{enrich_person_linkedin_profile_1.full_name}}",
        "description": "string",
        "columns": [
          {
            "name": "string",
            "type": "string",
            "structured_array_reference": "{{raw_to_structured_array_1.list.first_name}}"
          }
        ]
      }
    ]
  }
}

Rename Action

patch/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/name

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID (e.g. `enrich_company_linkedin_profile_1`). Returned by Add Action to Workflow.

Request body

namestringrequired

New display name for the action instance. Trimmed; cannot be empty after trimming.

Response

statusinteger

dataobject

action_instance_idstring

Echo of the path parameter — the action instance that was renamed. Unchanged by the rename; variable references ({{<action_instance_id>.<field>}}) keep working.

display_namestring

The stored display name.

Examples

Rename to a friendly label

Replace the auto-generated `enrich_company_linkedin_profile_1` with something readable for collaborators.

{
  "name": "Enrich primary contact"
}

Requestcurl

curl -X PATCH "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/name"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "name": "Enrich primary contact"
}'

Response200

{
  "status": 200,
  "data": {
    "action_instance_id": "enrich_company_linkedin_profile_1",
    "display_name": "Enrich primary contact"
  }
}

Move Action

patch/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/move

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance ID to move (e.g. `enrich_company_linkedin_profile_1`). Returned by Add Action to Workflow, or found in the Get Action Graph response.

Request body

afterstringoptional

Move the action immediately after this action_instance_id. Omit to move to the end of the chain. Pass "input" to move to the start of the chain (right after the synthetic input node). NOTE: this is an instance ID (e.g. scrape_company_linkedin_profile_1), not an action_id. Cannot equal the action being moved.

Response

statusinteger

dataobject

movedboolean

Always true on a 200 response — the action has been re-ordered.

action_instance_idstring

Echoes the action instance that was moved.

afterstring

The action_instance_id the moved action now sits immediately after. "input" indicates the moved action now sits at the start of the chain (right after the synthetic input node).

Examples

Move after a specific action

Place this action immediately after `scrape_company_linkedin_profile_1` in the chain.

{
  "after": "scrape_company_linkedin_profile_1"
}

Move to the start of the chain

Pass the literal `"input"` to position the action right after the synthetic input node.

{
  "after": "input"
}

Requestcurl

curl -X PATCH "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/move"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "after": "scrape_company_linkedin_profile_1"
}'

Response200

{
  "status": 200,
  "data": {
    "moved": true,
    "action_instance_id": "enrich_company_linkedin_profile_1",
    "after": "scrape_person_linkedin_profile_1"
  }
}

Reorder Waterfall Providers

patch/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/waterfall/{field_name}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance whose waterfall field to reorder (e.g. `find_work_email_1`).

field_namerequired

Snake-cased waterfall input field name from the action's `inputs[]` (e.g. `work_email`).

Request body

providersarrayrequired

Ordered list of provider apiIds. Must match the set of providers currently configured on the field — reorder only, no adds or removes.

Response

statusinteger

dataobject

reorderedboolean

action_instance_idstring

field_namestring

providersarray

Examples

Try Hunter before Prospeo

Reorder a work-email waterfall so Hunter runs first.

{
  "providers": ["hunter", "prospeo", "findymail"]
}

Requestcurl

curl -X PATCH "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/waterfall/:field_name"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "providers": [
    "hunter",
    "prospeo",
    "findymail"
  ]
}'

Response200

{
  "status": 200,
  "data": {
    "reordered": true,
    "action_instance_id": "find_work_email_1",
    "field_name": "work_email",
    "providers": [
      "hunter",
      "prospeo",
      "findymail"
    ]
  }
}

Save Action Note

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/notes

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance the note attaches to (e.g. `enrich_company_linkedin_profile_1`). Returned by **Add Action**, **Get Action**, or **Get Action Graph**. Reserved values `"input"` and `"graph"` return 404.

Request body

notestringrequired

Free-text note to attach to the action. Trimmed; cannot be empty after trimming.

Response

statusinteger

dataobject

action_instance_idstring

Echo of the path parameter — the action the note is attached to.

sheet_idstring

Sheet the note is scoped to.

notestring

The saved note text.

Examples

Park an action with rationale

Document why an action is configured but intentionally inactive.

{
  "note": "Skip until Phase 2 — vendor still negotiating contract terms."
}

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/notes"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "note": "Skip until Phase 2 — vendor still negotiating contract terms."
}'

Response200

{
  "status": 200,
  "data": {
    "action_instance_id": "enrich_company_linkedin_profile_1",
    "sheet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "note": "Skip until Phase 2 — vendor still negotiating contract terms."
  }
}

Sheets

2 endpoints

A workflow has one or more sheets — like tabs in a spreadsheet, except each tab has its own automation pipeline. Each sheet is an independent data table with its own inputs, actions, data rows, run history, and settings (auto_run, cache_enabled, cache_since). The main sheet is created automatically and the main sheet ID is the same as the workflow ID — additional sheets can be added and removed, but the main sheet is permanent.

Sheets connect to each other through the send_to_sheet action. Any sheet can send rows to any other sheet in the same workflow — this is how data flows between sheets.

Common use cases:

Array expansion — an action returns a structured_array (e.g. employees at a company). send_to_sheet fans each item into its own row on a new sheet for independent enrichment.
Segmentation — categorize and filter rows, then use send_to_sheet to route subsets to different sheets (e.g. Tier A to one sheet, Tier B+C to another) for clean data separation.
Enrichment staging — keep raw source data on the main sheet, then use send_to_sheet to send enriched and cleaned records to a separate output sheet.
Multi-source consolidation — import different data sources (CSVs, webhooks, CRM exports) into separate sheets, then use send_to_sheet to feed processed records from each source into a common destination sheet.

Every sheet-scoped operation (inputs, actions, data, runs) lives under /workflows/{workflow_id}/sheets/{sheet_id}/.... To operate on the main sheet, pass the workflow's ID as both {workflow_id} and {sheet_id} — the main sheet's ID equals the workflow ID.

abc123 (workflow ID = main sheet ID)

├── ghi789 — “Employees” (array expansion)

├── jkl012 — “Tier A Companies” (segmentation)

└── mno345 — “Enriched Leads” (enrichment staging)

Create Sheet

post/api/v1/workflows/{workflow_id}/sheets

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

Request body

namestringrequired

Sheet name. Not required to be unique within a workflow.

auto_runbooleanoptional

When true, the sheet's action chain runs automatically whenever new data rows arrive — via Add Data Rows or via a send_to_sheet action on another sheet. When false (default), runs must be triggered explicitly with Run Rows.

cache_enabledbooleanoptional

When true, a row with input column values identical to a previously-run row reuses the previous row's outputs instead of re-running the action chain. Matching compares every input column value on the row as a string, after variable references are resolved. Default: false.

cache_sincedateoptional

Earliest date (YYYY-MM-DD, UTC) from which cached runs are considered fresh. Runs performed on or after this date are reusable; runs performed before are ignored even when inputs match. Ignored when cache_enabled is false. Default: null — all cached runs are considered fresh regardless of age.

Response

statusinteger

dataobject

sheet_iduuid

UUID of the sheet. Pass as {sheet_id} on every sheet-scoped endpoint. Also used as target_sheet_id when another sheet routes data here via send_to_sheet.

workflow_iduuid

UUID of the workflow this sheet belongs to.

namestring

Sheet name as set at creation.

auto_runboolean

When true, the sheet's action chain runs automatically whenever new data rows arrive (via Add Data Rows or via send_to_sheet from another sheet). When false, runs must be triggered explicitly with Run Rows.

cache_enabledboolean

When true, a row with input column values identical to a previously-run row reuses the previous row's outputs instead of re-running the action chain. When false, every row triggers a fresh run.

cache_sincedate

Earliest date (YYYY-MM-DD, UTC) from which cached runs are considered fresh. Runs before this date are ignored even when inputs match. null when unset — all cached runs are considered fresh regardless of age.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "name": "Employees",
  "auto_run": false,
  "cache_enabled": false,
  "cache_since": "2026-03-17"
}'

Response201

{
  "status": 201,
  "data": {
    "sheet_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "name": "Employees",
    "auto_run": false,
    "cache_enabled": false,
    "cache_since": null
  }
}

Delete Sheet

delete/api/v1/workflows/{workflow_id}/sheets/{sheet_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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Parent workflow ID.

sheet_idrequired

Child sheet ID to delete. Must not equal `workflow_id` (the main sheet).

Response

statusinteger

dataobject

workflow_iduuid

UUID of the parent workflow the sheet belonged to.

sheet_iduuid

UUID of the child sheet that was deleted.

deletedboolean

Always true on a 200 response. Included so agents can branch on a single field.

Requestcurl

curl -X DELETE "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "sheet_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "deleted": true
  }
}

Run a Workflow

Process data through a configured workflow. The typical loop while building a workflow is: add a small number of rows (10–50), run, analyze the output, adjust the next action's configuration, run again. Expand to larger batches (100 → 1,000 → all) only once you are confident in the output.

Each cell — one action's execution on one row — is an independent execution unit with a lifecycle: queued → running → complete | failed. A row's run is a set of cells (one per action in the chain) that execute and bill independently. Runs are async — submit rows and poll List Rows for per-cell status and outputs.

Cost safety — read this carefully. Every action call consumes credits. A workflow with 5 actions × 10,000 rows is 50,000 action calls. Never run all rows without first running 10–50 and verifying output. Even when satisfied with the 10–50, still expand in batches (100 → 1,000 → all) before running the full dataset. Burning credits on a misconfigured workflow is the single biggest risk in this section.

Caching. When cache_enabled is on, a cell re-runs free if its resolved inputs exactly match a prior run. See Caching.

Sheets: to run a non-main sheet, use the sheet's ID in place of the workflow ID. The same endpoints work.

Add Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/rows

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request body

rowsarrayrequired

Rows to add. Each row is a JSON object whose keys are input field names (as defined by Add Inputs) and whose values match the field's declared type. Max 1,000 per call.

run_after_addstringoptional

What to run after rows are written. Scoped to the rows in this call only — pre-existing rows on the sheet are never touched. none (default) — add rows, don't run. first_10 — queue 10 of the newly-added rows for execution; recommended build-loop default. all — queue every newly-added row (⚠️ full credit cost = N rows × actions in chain; avoid until output is verified on first_10).

Response

statusinteger

warningsarray

Non-blocking issues across the batch (e.g. duplicate detection, normalized values). Shape matches Configure Action's warnings.

fieldstring

codestring

messagestring

dataobject

row_countinteger

Number of rows accepted and written. Equals row_ids.length.

row_idsarray

Flat array of newly-assigned row UUIDs, in request order. Rejected rows are not included. Copy directly into Run Rows's row_ids to execute.

rejectedarray

Rows the server couldn't accept (e.g. malformed shape, unknown fields). Valid rows in the same batch were still written — this list contains only the failures. Each entry echoes the original row content alongside field-level error codes so you can fix and resend just those rows.

rowobject

The original row content as you sent it — echoed back exactly so you can fix and resend without having to track positions in your request.

errorsarray

fieldstring

codestring

Machine-readable code indicating the failure reason (e.g. malformed_row, unknown_field).

messagestring

rows_queued_for_runinteger

How many newly-added rows were queued for execution. 0 when run_after_add: "none". 10 when "first_10". Equal to row_count when "all".

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/rows"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "rows": [
    {
      "linkedin_url": "https://linkedin.com/company/floqer",
      "email": "hello@floqer.com",
      "company_name": "Floqer"
    },
    {
      "linkedin_url": "https://linkedin.com/company/acme",
      "email": "contact@acme.com",
      "company_name": "Acme"
    },
    {
      "linkedin_url": "https://linkedin.com/company/globex",
      "email": "ops@globex.com",
      "company_name": "Globex"
    },
    {
      "linkedin_url": "https://linkedin.com/company/hooli",
      "email": "hi@hooli.com",
      "company_name": "Hooli"
    },
    {
      "linkedin_url": "https://linkedin.com/company/initech",
      "email": "info@initech.com",
      "company_name": "Initech"
    },
    {
      "linkedin_url": "https://linkedin.com/company/pied-piper",
      "email": "team@piedpiper.com",
      "company_name": "Pied Piper"
    },
    {
      "linkedin_url": "https://linkedin.com/company/soylent",
      "email": "info@soylent.com",
      "company_name": "Soylent"
    },
    {
      "linkedin_url": "https://linkedin.com/company/dundermifflin",
      "email": "sales@dundermifflin.com",
      "company_name": "Dunder Mifflin"
    },
    {
      "linkedin_url": "https://linkedin.com/company/stark",
      "email": "hi@stark.com",
      "company_name": "Stark Industries"
    },
    {
      "linkedin_url": "https://linkedin.com/company/wayne",
      "email": "info@wayne.com",
      "company_name": "Wayne Enterprises"
    },
    {
      "linkedin_url": "https://linkedin.com/company/umbrella",
      "email": "contact@umbrella.com",
      "company_name": "Umbrella"
    }
  ],
  "run_after_add": "first_10"
}'

Response201

{
  "status": 201,
  "warnings": [],
  "data": {
    "row_count": 11,
    "row_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567002",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567003",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567004",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567005",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567006",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567007",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567008",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567009",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567010",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567011"
    ],
    "rejected": [],
    "rows_queued_for_run": 10
  }
}

Run Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/run

Runs a subset of the sheet's rows through the action chain. Specify the subset in one of two 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.

Exactly one of row_ids or first_10 must be provided. Both or neither returns 400.

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 (requires confirm_sheet_id for safety).

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

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request body

row_idsarrayoptional

Row UUIDs to queue through the action chain. Get these from Add Rows (row_ids response field) or List Rows. Rows on the sheet not included here are not re-run. Mutually exclusive with first_10.

first_10booleanoptional

Shortcut for "run the first 10 rows on the sheet" (by created_at ascending). Useful for experimentation and sampling on existing sheets. Mutually exclusive with row_ids. Pass true to enable; omit or pass false to use row_ids instead.

Response

statusinteger

messagestring

dataobject

rows_queuedinteger

Number of rows queued for execution. Equals row_ids.length when row_ids was provided, or 10 (or fewer if the sheet has fewer rows) when first_10: true was provided.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/run"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "row_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567002",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567003"
  ]
}'

Response200

{
  "status": 200,
  "message": "Rows queued for execution",
  "data": {
    "rows_queued": 3
  }
}

Run All Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/run-all

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Response

statusinteger

messagestring

dataobject

rows_queuedinteger

Number of rows queued for execution. Equals the total row count on the sheet at the time of the call.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/run-all"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "message": "All rows queued for execution",
  "data": {
    "rows_queued": 157
  }
}

Run Action

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/run

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.
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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

action_instance_idrequired

The action instance to run. Returned by **Add Action**, **Get Action**, or **Get Action Graph**.

Request body

row_idsarrayoptional

Row UUIDs to queue against the targeted action. From Add Rows (row_ids response field) or List Rows. Omit or pass an empty array to run every row on the sheet.

run_next_actionbooleanoptional

Whether to continue execution down the chain after the targeted action finishes. false (default) runs ONLY the targeted action — all actions downstream of it are skipped. true runs the targeted action then continues through the rest of the chain, re-running every action that comes after it.

Response

statusinteger

messagestring

dataobject

rows_queuedinteger

Number of rows queued for execution against the targeted action. 0 when the sheet has no rows (and row_ids was empty / omitted).

Examples

Run only this action for selected rows

Default behavior. Useful for retrying a few rows that failed at this action, or spot-checking changes after a **Configure Action** edit.

{
  "row_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567002"
  ]
}

Refresh the chain after editing this action

After **Configure Action** changes this action's inputs, set `run_next_action: true` to re-run this action AND everything downstream of it in the chain in one call.

{
  "row_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567001"],
  "run_next_action": true
}

Run every row on the sheet

Pass an empty `row_ids` array to queue every row currently on the sheet against the targeted action.

{
  "row_ids": []
}

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/actions/:action_instance_id/run"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "row_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567002"
  ],
  "run_next_action": false
}'

Response200

{
  "status": 200,
  "message": "Rows queued for execution",
  "data": {
    "rows_queued": 3
  }
}

List Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/rows/list

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 URL under outputs_ref when the payload is large (e.g. LinkedIn profile scrapes, enrichment blobs — fetch the URL with your API key to read the data). Failed cells carry an error message. queued and running cells carry only status.

Paginated — default page size 20, max 200.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request body

row_idsarrayoptional

Filter to specific rows. Omit to return all rows on the sheet (paginated). Max 200 IDs per call — if you have more than 200 to poll, chunk your IDs across multiple calls. Mutually exclusive with filters / status_filters / created_at — combining them returns 400.

page_nointegeroptional

Page number (1-indexed). Only meaningful when browsing (no row_ids) or when row_ids count exceeds page_size.

page_sizeintegeroptional

Rows per page. Defaults to 20. Maximum 200.

filtersarrayoptional

Browse-mode only (omit row_ids). Value filters on sheet input columns — action-output filtering is not exposed yet. Each entry has variable (an {{input.<column>}} reference token), operator, and values. Operators: is equal to, not equal to, is empty, not empty, contains, does not contain, contains any of, not contains any of, greater than, less than. Most operators take exactly one value; contains any of / not contains any of accept one or more (exact match each); is empty / not empty ignore values; greater than / less than are numeric. Multiple entries are AND-ed together.

status_filtersarrayoptional

Browse-mode only (omit row_ids). Match rows by per-action cell status. Each entry pairs an action_instance_id with exactly one of is (status matches one of) or is_not (status matches none of) — passing both, or neither, returns 400. Status values use the public vocabulary (queued | running | complete | failed | error | condition_not_met); the server expands them to the engine's internal statuses (e.g. queued covers both payloadFilled and checkingNextSource). Multiple entries are AND-ed together.

created_atobjectoptional

Browse-mode only (omit row_ids). Single time filter on row creation. operator is one of equals to, greater than, greater than or equals to, less than, less than or equals to, is between. values is [ISO timestamp] for the single-value operators or [start, end] for is between (uses its own dialect, separate from filters[]).

Response

statusinteger

dataobject

rowsarray

Rows on this page, in insertion order.

row_iduuid

UUID assigned by Add Rows.

row_statusstring

Row-level execution summary — a quick check without iterating every cell. pending: the row has never been run (cells is {}). running: at least one cell is queued or running. complete: all cells reached complete. has_failures: terminal state — no cell is still running and at least one cell has status: "failed".

created_atdate-time

UTC timestamp (ISO 8601) when the row was added to the sheet via Add Rows.

inputsobject

Input column values as the row was created. Keys match the sheet's input field names.

cellsobject

One entry per action in the sheet's chain, keyed by action_instance_id (e.g. scrape_company_linkedin_profile_1). Empty {} for rows that have never been run (added with run_after_add: "none" and not subsequently executed via Run Rows).

total_countinteger

Total rows on the sheet across all pages.

page_nointeger

page_sizeinteger

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/rows/list"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "filters": [
    {
      "variable": "{{input.email}}",
      "operator": "contains",
      "values": [
        ".com"
      ]
    }
  ],
  "status_filters": [
    {
      "action_instance_id": "enrich_company_linkedin_profile_1",
      "is_not": [
        "failed",
        "error"
      ]
    }
  ],
  "created_at": {
    "operator": "greater than",
    "values": [
      "2026-05-07T22:14:00Z"
    ]
  },
  "page_size": 20
}'

Response200

{
  "status": 200,
  "data": {
    "rows": [
      {
        "row_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
        "row_status": "complete",
        "created_at": "2026-04-20T10:30:00Z",
        "inputs": {
          "linkedin_url": "https://linkedin.com/company/floqer",
          "email": "hello@floqer.com",
          "company_name": "Floqer"
        },
        "cells": {
          "scrape_company_linkedin_profile_1": {
            "status": "complete",
            "outputs_ref": {
              "url": "https://storage.floqer.com/orgs/acme/cells/a1b2c3d4-scrape-1.json",
              "size_bytes": 204800
            }
          },
          "ai_generate_content_1": {
            "status": "complete",
            "outputs": {
              "generated_content": "Hi Floqer team — noticed you raised a Series A..."
            }
          }
        }
      },
      {
        "row_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567002",
        "row_status": "running",
        "created_at": "2026-04-20T10:30:02Z",
        "inputs": {
          "linkedin_url": "https://linkedin.com/company/acme",
          "email": "contact@acme.com",
          "company_name": "Acme"
        },
        "cells": {
          "scrape_company_linkedin_profile_1": {
            "status": "running"
          },
          "ai_generate_content_1": {
            "status": "queued"
          }
        }
      },
      {
        "row_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567003",
        "row_status": "has_failures",
        "created_at": "2026-04-20T10:30:05Z",
        "inputs": {
          "linkedin_url": "not-a-real-url",
          "email": "ops@globex.com",
          "company_name": "Globex"
        },
        "cells": {
          "scrape_company_linkedin_profile_1": {
            "status": "failed",
            "error": "Provider returned 404 for the given URL."
          },
          "ai_generate_content_1": {
            "status": "failed",
            "error": "Skipped: upstream action scrape_company_linkedin_profile_1 failed."
          }
        }
      }
    ],
    "total_count": 11,
    "page_no": 1,
    "page_size": 20
  }
}

Delete Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/rows/delete

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Request body

row_idsarrayrequired

Row UUIDs to delete. From Add Rows (row_ids response) or List Rows. Max 200 per call.

Response

statusinteger

dataobject

deleted_countinteger

Number of rows actually deleted. Equals deleted_row_ids.length.

deleted_row_idsarray

UUIDs that were successfully deleted, in request order (skipping any rejected).

rejectedarray

Row UUIDs the server couldn't delete. Rows that WERE deleted in the same batch are still gone — this list contains only the failures.

row_idstring

The UUID you sent that couldn't be deleted.

errorstring

Human-readable reason (e.g. Row not found on this sheet).

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/rows/delete"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "row_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567002",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567003"
  ]
}'

Response200

{
  "status": 200,
  "data": {
    "deleted_count": 2,
    "deleted_row_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567001",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567002"
    ],
    "rejected": [
      {
        "row_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567003",
        "error": "Row not found on this sheet"
      }
    ]
  }
}

Delete All Rows

post/api/v1/workflows/{workflow_id}/sheets/{sheet_id}/rows/delete-all

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

sheet_idrequired

Sheet ID. To operate on the workflow's main sheet, pass the workflow's ID as `sheet_id` — the main sheet's ID equals the workflow ID.

Response

statusinteger

dataobject

deleted_countinteger

Number of rows deleted. 0 if the sheet was already empty.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/:workflow_id/sheets/:sheet_id/rows/delete-all"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "deleted_count": 157
  }
}

Manage Workflows

Admin-only CRUD on workflow records — create, list, inspect (Get Workflow Overview), and delete. No configuration happens here; everything about building a workflow (inputs, actions, sheets, data, runs) lives in Build a Workflow and Run a Workflow.

Create Workflow

post/api/v1/workflows/

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).

Requires API key. Authentication ↑

Request body

namestringrequired

Workflow name. Not required to be unique in the organization.

Response

statusinteger

dataobject

workflow_iduuid

UUID of the newly created workflow. Use this for {workflow_id} (and {sheet_id} for main-sheet operations) across every other endpoint.

namestring

Name as set in the request.

created_atdate-time

UTC timestamp (ISO 8601).

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/workflows/"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "name": "Lead Enrichment Pipeline"
}'

Response201

{
  "status": 201,
  "data": {
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "name": "Lead Enrichment Pipeline",
    "created_at": "2026-04-20T10:30:00Z"
  }
}

List Workflows

get/api/v1/workflows/

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.

Requires API key. Authentication ↑

Response

statusinteger

dataarray

workflow_iduuid

UUID of the workflow. Use this with every endpoint that takes {workflow_id}.

namestring

Workflow name as set at creation.

created_atdate-time

UTC timestamp (ISO 8601) when the workflow was created.

updated_atdate-time

UTC timestamp (ISO 8601) of the most recent configuration change (name, inputs, actions, sheet settings).

last_run_atdate-time

UTC timestamp (ISO 8601) of the most recent run queued on any sheet in this workflow. null if the workflow has never been run.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": [
    {
      "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
      "name": "Lead Enrichment Pipeline",
      "created_at": "2026-04-18T09:12:00Z",
      "updated_at": "2026-04-20T10:30:05Z",
      "last_run_at": "2026-04-20T10:32:00Z"
    },
    {
      "workflow_id": "9a2fc018-2d4a-4e41-b0e7-112233445566",
      "name": "Inbound Demo Scoring",
      "created_at": "2026-04-10T14:05:00Z",
      "updated_at": "2026-04-19T22:14:00Z",
      "last_run_at": null
    }
  ]
}

Get Workflow Overview

get/api/v1/workflows/{workflow_id}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

Response

statusinteger

dataobject

workflow_iduuid

UUID of the workflow.

namestring

Workflow name as set at creation.

created_atdate-time

UTC timestamp (ISO 8601) when the workflow was created.

updated_atdate-time

UTC timestamp (ISO 8601) of the most recent configuration change.

last_run_atnull | string

UTC timestamp (ISO 8601) of the most recent run queued on any sheet. null if never run.

is_ownerboolean

true when the caller is the workflow owner. shared_users is populated only when this is true.

shared_usersarray

Emails the workflow is shared with. Populated only when is_owner is true; otherwise [].

sheetsarray

Every sheet in the workflow with settings and webhook URL. sheets[0] is the main sheet.

sheet_iduuid

UUID of the sheet. Pass as {sheet_id} on sheet-scoped endpoints and as target_sheet_id in send_to_sheet.

namestring

Sheet name as set at creation.

is_main_sheetboolean

true for the main sheet — auto-created with the workflow and has sheet_id === data.workflow_id.

auto_runboolean

When true, the sheet's action chain runs automatically whenever new rows arrive.

cache_enabledboolean

When true, identical input rows reuse prior outputs instead of re-running the chain.

cache_sincenull | string

Earliest date (YYYY-MM-DD, UTC) from which cached runs are considered fresh. null means all cached runs count.

webhook_urlnull | string

POST URL for pushing rows into this sheet via webhook. null when no webhook input is configured.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/workflows/:workflow_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "name": "Lead Enrichment Pipeline",
    "created_at": "2026-04-20T10:30:00Z",
    "updated_at": "2026-04-20T10:30:00Z",
    "last_run_at": null,
    "is_owner": true,
    "shared_users": [
      "colleague@example.com"
    ],
    "sheets": [
      {
        "sheet_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
        "name": "Lead Enrichment Pipeline",
        "is_main_sheet": true,
        "auto_run": false,
        "cache_enabled": false,
        "cache_since": null,
        "webhook_url": "https://workers.floqer.com/v2/trigger/webhook?id=eyJ..."
      },
      {
        "sheet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Employees",
        "is_main_sheet": false,
        "auto_run": true,
        "cache_enabled": true,
        "cache_since": "2026-03-17",
        "webhook_url": null
      }
    ]
  }
}

Delete Workflow

delete/api/v1/workflows/{workflow_id}

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.

Requires API key. Authentication ↑

Path parameters

workflow_idrequired

Workflow ID.

Response

statusinteger

dataobject

workflow_iduuid

UUID of the workflow that was deleted.

deletedboolean

Always true on a 200 response. Included so agents can branch on a single field.

Requestcurl

curl -X DELETE "https://api.floqer.com/api/v1/workflows/:workflow_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "deleted": true
  }
}

Sources

Sources pull external data into Floqer, where it lands as rows your workflows can enrich, score, and act on. This is the inbound counterpart to a workflow's actions: an action pushes data out to an integration; a source brings data in. Each source is addressed by a source slug under /api/v1/sources/{source_id}.

The operations fall into two stages:

Build — prepare and persist a source:

Preview Source — see the records that would be imported for a given payload, without persisting anything. Use it to validate your selection before you commit.
Create Source — persist the source and start importing. Whether it imports once or keeps importing over time is source-specific and set in the body.
Get Source Field Options — resolve the dynamic values a payload field expects. When a field's value comes from a connected system, fetch its options here first, then reference the returned values in your payload.

Manage — operate on sources you've already created:

List Sources — list the source instances you've created (newest first), each with its instance source_instance_id, its type slug (source_id), status, and row count. Use it to find the source_instance_id to sync.
Get Source Data — page through the rows imported into a created source. Use it to poll while a backfill runs or to inspect the dataset before syncing.
Sync Source to Workflow — connect a created source to a workflow and backfill it with the source's existing rows, mapping source fields onto the workflow's inputs.
Pause or Resume Source — pause or resume an ongoing source's recurring imports.

Discovering a source's payload. There is no endpoint that describes a source's body shape. The route schema accepts any JSON object; the real per-source body, field semantics, supported filters, and any prerequisites (such as a connected integration) are validated inside the handler and documented in full at /docs/source-detail/{source_id}.txt. Load that file once before constructing a payload — it is the authoritative reference, the same way the action catalog is for actions.

Scopes: Preview, Get Source Field Options, List Sources, and Get Source Data need sources:read; Create, Sync, and Pause/Resume need sources:write.

Build

3 endpoints

Building a source is a short loop: resolve any dynamic field values with Get Source Field Options, Preview the records your payload would import, then Create the source to persist it and start importing.

The request body is specific to each source type — the route only checks that it's a JSON object. Each source's payload fields, filters, and any prerequisites (such as a connected integration) are documented in its detail file. Load it before constructing a payload.

source-detail — per-source payload reference

Preview Source

post/api/v1/sources/{source_id}/preview

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.

Requires API key. Authentication ↑

Path parameters

source_idrequired

Source slug identifying the source TYPE. Currently supported: `extract_from_website`, `find_companies`, `find_companies_by_buying_intent`, `find_companies_by_tech_stack`, `find_companies_from_sales_navigator`, `find_companies_hiring`, `find_job_postings`, `find_linkedin_post_reactors`, `find_people`, `find_people_from_sales_navigator`, `import_from_fireflies`, `import_from_google_sheets`, `import_from_hubspot`, `import_from_pipedrive`, `import_from_salesforce`, `import_from_slack`, `import_from_snowflake`, `import_from_stripe`, `import_from_typeform`, `search_local_businesses`, `search_x_tweets`, `track_job_postings`, `track_linkedin_posts`, `track_personal_website_visitors`, `track_website_visitors`, `track_x_posts`. Browse them in [`/docs/source-catalog.txt`](/docs/source-catalog.txt); see `/docs/source-detail/{source_id}.txt` for each source's payload.

Request body

The request body shape depends on source_id — each source type defines its own preview payload. The route only checks that the body is a JSON object; the accepted fields are documented per source in /docs/source-detail/{source_id}.txt and validated inside the handler, where unknown or malformed fields return 400.

Response

statusinteger

dataobject

dataarray

Preview rows (max 100). Each row's keys depend on the source's payload.

metadataobject

total_resultsinteger

Total matching records upstream — may exceed the 100 rows returned in data.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/sources/:source_id/preview"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{}'

Response200

{
  "status": 200,
  "data": {
    "data": [
      {
        "email": "ada@example.com",
        "first_name": "Ada",
        "last_name": "Lovelace"
      },
      {
        "email": "alan@example.com",
        "first_name": "Alan",
        "last_name": "Turing"
      }
    ],
    "metadata": {
      "total_results": 1240
    }
  }
}

Create Source

post/api/v1/sources/{source_id}

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.

Requires API key. Authentication ↑

Path parameters

source_idrequired

Source slug identifying the source TYPE. Currently supported: `extract_from_website`, `find_companies`, `find_companies_by_buying_intent`, `find_companies_by_tech_stack`, `find_companies_from_sales_navigator`, `find_companies_hiring`, `find_job_postings`, `find_linkedin_post_reactors`, `find_people`, `find_people_from_sales_navigator`, `import_from_fireflies`, `import_from_google_sheets`, `import_from_hubspot`, `import_from_pipedrive`, `import_from_salesforce`, `import_from_slack`, `import_from_snowflake`, `import_from_stripe`, `import_from_typeform`, `search_local_businesses`, `search_x_tweets`, `track_job_postings`, `track_linkedin_posts`, `track_personal_website_visitors`, `track_website_visitors`, `track_x_posts`. Not to be confused with the UUID returned in the response. Browse them in [`/docs/source-catalog.txt`](/docs/source-catalog.txt); see `/docs/source-detail/{source_id}.txt`.

Request body

The request body shape depends on source_id — typically the source's preview payload plus its create-only fields (e.g. a display name). The route only checks that the body is a JSON object; the accepted fields are documented per source in /docs/source-detail/{source_id}.txt and validated inside the handler, where unknown or malformed fields return 400.

Response

statusinteger

dataobject

source_instance_iduuid

UUID of the newly created source instance. Distinct from the source_id slug in the request URL — pass it to Sync / Get Source Data / Pause-Resume.

namestring

Display name echoed from the request (trimmed).

created_atdate-time

UTC timestamp (ISO 8601) of source creation.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/sources/:source_id"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{}'

Response201

{
  "status": 201,
  "data": {
    "source_instance_id": "c7e3a1b2-9f4d-4a8c-b1e6-2d5f6a7b8c90",
    "name": "Customer accounts",
    "created_at": "2026-05-25T09:12:00Z"
  }
}

Get Source Field Options

post/api/v1/sources/{source_id}/options/{field_name}

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.

Requires API key. Authentication ↑

Path parameters

source_idrequired

Source slug — the same slug used on the source's Preview / Create endpoint (e.g. `import_from_hubspot`, `find_people_from_sales_navigator`). See `/docs/source-detail/{source_id}.txt`. Not every source exposes dynamic options — `find_companies`, `find_people`, and `track_linkedin_posts` have none today; Sales Navigator sources expose region autocomplete via `location` and/or `company_headquarters`.

field_namerequired

Snake-cased payload field to fetch options for. Matches a key on the source's Preview / Create body. The supported field names are listed in the source's detail doc.

Request body

contextobjectoptional

Earlier cascading selections this resolver depends on, keyed by the parent field's name on the source's payload. Omit (or send an empty body) for resolvers that don't cascade. Calling a cascading resolver without its required key returns 400 listing the accepted spellings.

Response

statusinteger

dataobject

optionsarray

Option values the resolver returned.

valuestring

The value to send back via the source's Preview / Create payload.

labelstring

Human-readable label for the option.

extrasobject

Per-integration metadata, when present. Shape varies by integration — use it for richer rendering when needed.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/sources/:source_id/options/:field_name"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "context": {}
}'

Response200

{
  "status": 200,
  "data": {
    "options": [
      {
        "value": "123",
        "label": "All accounts"
      },
      {
        "value": "456",
        "label": "Signups — last 30 days"
      }
    ]
  }
}

Manage

4 endpoints

Once a source exists, manage it by its source_id UUID — the value returned by Create Source. Sync Source to Workflow connects it to a workflow — mapping the source's fields onto the workflow's inputs with field_mapping and backfilling the workflow with the source's existing rows.

List Sources

get/api/v1/sources/

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.

Requires API key. Authentication ↑

Response

statusinteger

dataarray

The caller's sources, newest first.

source_instance_idstring

Source instance UUID — pass to Sync Source to Workflow (POST /api/v1/sources/{source_instance_id}/sync) or Get Source Data (GET /api/v1/sources/{source_instance_id}/data).

namestring

Display name given at creation.

source_idstring

Public source-type slug (e.g. import_from_hubspot, find_companies) — the identifier used by Preview / Create / Get Source Field Options.

statusstring

Source status: active (live, re-importing), completed (one-time import, won't refresh), paused, paused_out_of_credits, expired, or deleted.

lead_countinteger

Rows imported so far.

created_atdate-time

UTC creation timestamp (ISO 8601).

expiration_datestring

When an active source stops firing. null for one-time sources.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/sources/"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": [
    {
      "source_instance_id": "b7e2c1a0-4d8f-4a21-9c33-5e6f7a8b9c01",
      "name": "AI Posts from CEOs",
      "source_id": "track_linkedin_posts",
      "status": "active",
      "lead_count": 128,
      "created_at": "2026-05-27T12:00:00Z",
      "expiration_date": "2026-06-26"
    },
    {
      "source_instance_id": "a1d4f9c3-2b6e-4f70-8a12-3c4d5e6f7a8b",
      "name": "US Mid-Market SaaS",
      "source_id": "find_companies",
      "status": "completed",
      "lead_count": 1000,
      "created_at": "2026-05-26T09:30:00Z",
      "expiration_date": null
    }
  ]
}

Get Source Data

get/api/v1/sources/{source_instance_id}/data

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.

Requires API key. Authentication ↑

Path parameters

source_instance_idrequired

Source instance UUID — the `source_instance_id` returned by **Create Source**.

Query parameters

page_nointeger

1-indexed page number. Defaults to 1.

page_sizeinteger

Rows per page. Defaults to 20; capped at 200.

Response

statusinteger

dataobject

rowsarray

Imported rows for this page. Field names depend on the source type.

total_countinteger

Total number of rows stored for this source.

page_nointeger

1-indexed page number returned.

page_sizeinteger

Page size used for this response.

Requestcurl

curl -X GET "https://api.floqer.com/api/v1/sources/:source_instance_id/data"
  -H "Authorization: Bearer floq_YOUR_API_KEY"

Response200

{
  "status": 200,
  "data": {
    "rows": [
      {
        "email": "ada@example.com",
        "firstname": "Ada",
        "lastname": "Lovelace"
      },
      {
        "email": "grace@example.com",
        "firstname": "Grace",
        "lastname": "Hopper"
      }
    ],
    "total_count": 128,
    "page_no": 1,
    "page_size": 20
  }
}

Sync Source to Workflow

post/api/v1/sources/{source_instance_id}/sync

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.

run controls whether backfilled rows execute the workflow: all (default) runs every row, first_10 runs the first 10 and just loads the rest, none loads rows without running. push_existing (default true) toggles the backfill entirely — set it false to connect the source without importing its current rows.

Requires API key. Authentication ↑

Path parameters

source_instance_idrequired

Source instance UUID — the `source_instance_id` returned by **Create Source**.

Request body

workflow_iduuidrequired

UUID of the destination workflow.

field_mappingobjectrequired

Map of workflow input reference → source field. Keys are input.<field> references from the workflow's inputs (case-sensitive); each value is the source field NAME — the row's top-level key exactly as it appears in the Preview response (e.g. Name, email), never a nested path like Name.value. A key that doesn't match a workflow input returns 400.

push_existingbooleanoptional

Whether to backfill the workflow with the source's current rows. Defaults to true; set false to connect without importing existing rows.

runstringoptional

Controls whether backfilled rows execute the workflow: all (default) runs every row, first_10 runs the first 10 and loads the rest, none loads rows without running.

Response

statusinteger

dataobject

source_instance_iduuid

The connected source's instance UUID.

workflow_iduuid

The destination workflow's UUID.

push_existingboolean

Whether existing rows were queued for backfill.

runstring

The run mode applied to backfilled rows.

fields_mappedinteger

Number of workflow inputs mapped.

Requestcurl

curl -X POST "https://api.floqer.com/api/v1/sources/:source_instance_id/sync"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
  "field_mapping": {
    "input.email": "email",
    "input.first_name": "firstname",
    "input.last_name": "lastname"
  },
  "push_existing": true,
  "run": "first_10"
}'

Response201

{
  "status": 201,
  "data": {
    "source_instance_id": "c7e3a1b2-9f4d-4a8c-b1e6-2d5f6a7b8c90",
    "workflow_id": "531952c2-3d07-4be2-8c4b-733acba3187b",
    "push_existing": true,
    "run": "first_10",
    "fields_mapped": 3
  }
}

Pause or Resume Source

patch/api/v1/sources/{source_instance_id}/status

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.

Requires API key. Authentication ↑

Path parameters

source_instance_idrequired

Source instance UUID — the `source_instance_id` returned by **Create Source**.

Request body

statusstringrequired

paused stops recurring runs; active resumes them.

Response

statusinteger

dataobject

source_instance_iduuid

The source instance UUID.

statusstring

The source's new public status.

Requestcurl

curl -X PATCH "https://api.floqer.com/api/v1/sources/:source_instance_id/status"
  -H "Authorization: Bearer floq_YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "status": "active"
}'

Response200

{
  "status": 200,
  "data": {
    "source_instance_id": "b7e2c1a0-4d8f-4a21-9c33-5e6f7a8b9c01",
    "status": "paused"
  }
}

Caching

Workflow execution is cached per cell — one action's execution on one row. When cache_enabled is on for a sheet (default: on), re-running a cell whose resolved inputs match a prior run pulls the output from the cache — the cell is not re-executed and not re-billed. This is what makes the iterative build loop affordable.

The simple rule. If a cell's resolved inputs exactly match a prior run within the cache window, you don't pay for that cell. Any difference — including a single whitespace character — is a cache miss and the cell runs fresh.

Cache key

A cache hit requires an exact match on two things, within the cache window:

The cell's resolved inputs — the final values after substituting references like {{input.linkedin_url}} or {{scrape_company_linkedin_profile_1.company_name}}, plus any static parameters (prompt text, model, provider). A whitespace change in a prompt template changes the resolved prompt, so it counts.
A cache entry newer than the sheet's cache_since timestamp — entries older than cache_since are ignored.

What invalidates the cache

Action configuration changes — any edit: a different prompt, a changed model, a swapped provider. Even a single whitespace change counts, because the hash is computed over the exact string. Re-running after the edit re-executes and re-bills every cell for that action.
Resolved input changes — when an upstream cell produces a different output on a re-run, the downstream cell's resolved inputs change, its hash changes, and it re-runs. Where the upstream cell's output is identical, the downstream cell still hits cache.
Cache window advancing — advancing cache_since invalidates older entries in bulk (see below).
New cells — cells that have never been executed have no cache entry to hit, so the first run always bills in full.

Cost implication of iteration

In the “run 10, tweak action 3's prompt, run 10 again” loop (10 rows of data):

Action 1 and action 2 cells hit cache for every row (config and inputs unchanged) — no re-bill.
Action 3 re-runs for all 10 of its cells (config hash changed) — bills for all 10.
Downstream cells — action 4, action 5, and so on — re-run only for rows where action 3's output changed. For rows where action 3 produces the same output after your edit, the downstream cells for those rows see identical resolved inputs and still hit cache. For rows where action 3's output differs, the downstream cell's input hash changes and it re-runs.

How far the cascade travels depends on how deterministic each action is. Stable lookups and scrapers of unchanging data often produce identical output across re-runs, leaving downstream cells intact. Generative actions (AI content with non-zero temperature, waterfall providers) are more likely to produce different output, so downstream cells cascade further.

When budgeting a re-run, assume the worst case — every downstream cell re-bills. Treat downstream cache hits as a bonus, not a guarantee.

Disabling caching

Set cache_enabled: false on a sheet via Update Workflow. Every run then executes every action fresh, regardless of prior runs. Useful for non-deterministic actions you want to re-sample (e.g. generative AI with high temperature) or for debugging cache behavior. With caching off, every re-run is billed in full.

cache_since

Sheets also carry a cache_since timestamp. Only cache entries produced after this timestamp are valid — advancing it invalidates older entries in bulk without having to disable caching entirely.