ACTION_ID: call_shortcut
NAME: Call Shortcut
CATEGORY: Floq Tools
CREDITS: 0 (the call is free; the called shortcut's own actions bill as usual)

Runs a published shortcut once per row and returns its outputs as columns on
this row.

1. INPUTS

shortcut (string, required)
  The shortcut to call: an `id` from List Shortcuts
  (GET /api/v1/shortcuts?search=<name>). Pick one with `callable: true`.
  List Shortcuts is the only source: Get Action Field Options has no
  resolver for this field (400).
  Setting it builds this action's inputs and outputs from the shortcut's
  latest published version. Pointing the action at a different shortcut
  resets its inputs to empty and replaces its output columns, so send the
  new shortcut's `inputs` in the same request.
  - 404 SHORTCUT_NOT_FOUND — not a shortcut you can see, or a name sent
    instead of an id.
  - 409 SHORTCUT_NOT_PUBLISHED — it has no published version; republish it
    in the Floqer app first.
  - 400 SHORTCUT_SELF_CALL — it is backed by the workflow you are editing,
    or its published version calls a shortcut backed by this workflow.

inputs (object)
  One entry per shortcut input you map, keyed by the input's `reference`
  from the shortcut's input_schema (the same keys Run Shortcut takes):
    { "domain": "{{input.domain}}", "name": "{{input.company_name}}" }
  Values are strings: a `{{ref}}`, a literal, or a mix. Inputs you leave out
  keep their current value (empty on a new action). A reference the shortcut
  does not have is ignored with an `unknown_field` warning that lists the
  valid ones. A required input left empty with no default returns a
  `missing_required_input` warning on that response only (Get Action does
  not repeat it): rows fail before the shortcut runs, with the cell error
  "An unexpected error occurred.", until it is set, and nothing is billed
  for them. A required input with a default (input_schema `defaultValue`)
  uses the default when left empty.

2. OUTPUTS

One field per output of the called shortcut, named after it (snake_cased):
a shortcut returning "Company Name" gives `{{<action_instance_id>.company_name}}`.
Outputs that share a name are numbered in order — `email`, `email_2`,
`email_3` — the same keys Get Shortcut reports. Add Action's 201 lists them
when `shortcut` is set there; Configure Action's 200 returns only the
action_instance_id, so GET the action (or Get Action Outputs) to read them
after a PATCH.

3. HOW TO CONFIGURE

1. Find the shortcut:
   GET /api/v1/shortcuts?search=enrich
   → pick an entry with "callable": true; read its `id` and the
     `input_schema[].reference` keys.

2. Add the action and configure it (or pass the same `inputs` to Add Action):
   POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/add
   { "action_id": "call_shortcut" }

   PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}
   {
     "inputs": {
       "shortcut": "<shortcut id>",
       "inputs": { "domain": "{{input.domain}}" }
     }
   }

3. Use the `outputs[].reference` tokens (from Add Action's 201 or Get Action)
   in downstream actions.

4. KEY NOTES

- Every call runs the shortcut's LATEST published version. When the
  shortcut gains outputs, re-send `shortcut` (the same id) to add their
  columns; existing columns and their references are kept.
- An output the shortcut's owner later removes stays as a column here and
  resolves to "".
- Pointing the action at a different shortcut replaces all of its output
  columns. Actions that referenced the old ones come back in a
  `broken_downstream_reference` warning; reconfigure them.
- Get Action returns `shortcut` as the id List Shortcuts gave you and
  `inputs` as the same map you sent, so GET → edit → PATCH round-trips.
- Call shortcuts that do not call back into this workflow. Floqer refuses
  a direct or one-hop loop (A calls B, B calls A) with SHORTCUT_SELF_CALL;
  a longer loop keeps starting new runs, each billed, until someone stops it.
- A call that fails inside the shortcut fails this cell with the shortcut
  run's error, often a generic one (e.g. "Data not formattable"). The usual
  fix is to re-run the cell. The failing step's own message is on the
  shortcut's flow, which you may not have access to.

5. WHERE IT FITS IN A WORKFLOW

Anywhere after the values it needs. Upstream: the actions producing its
inputs. Downstream: anything that reads its outputs.

6. WHEN TO USE

- The same multi-step enrichment is needed in several workflows: build it
  once, publish it as a shortcut, call it from each.
- You want another team's packaged workflow as one step, without copying
  its actions.

7. WHEN NOT TO USE

- You need the result for one record outside any workflow — call Run
  Shortcut directly.
- You want to send rows to another workflow without getting anything back —
  use push_data_to_another_floqer_workflow.

Last updated: 2026-09-28.