ACTION_ID: http_api_call
NAME: HTTP API Call
CATEGORY: sheets
CREDITS: 0

Make an API call.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

method (dropdown, required)
  Method. Choose the HTTP method. Values: GET, POST, PATCH, PUT,
  DELETE.

endpoint (string, required)
  Endpoint. Enter the endpoint to send the requests to.

query_params (raw_array, optional)
  Query Params. Enter the Query Parameters of your Call. Each item is
  `{name, value}` — `value` accepts `{{ref}}` tokens or literals.

body (raw_array, required)
  Body. Enter the Data Body to include in the Call. Each item becomes a
  JSON key on the outgoing request body. Each item is `{name, value}` —
  `value` accepts `{{ref}}` tokens or literals.

headers (raw_array, optional)
  Headers. Enter any header fields to set for the Call. Each item is
  `{name, value}` — `value` accepts `{{ref}}` tokens or literals (auth
  tokens, content-type, etc.).

================================================================================
2. OUTPUTS
================================================================================

Dynamic — there are no fixed output fields. The output schema is
discovered after the first run via Get Action Outputs (see KEY NOTES);
each top-level key on the response JSON becomes a referenceable
output. Until the first run, no outputs are surfaced.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body
(PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}):

{
  "inputs": {
    "method": "POST",
    "endpoint": "https://api.example.com/v1/score",
    "headers": [
      { "name": "Authorization", "value": "Bearer YOUR_API_KEY" },
      { "name": "Content-Type",  "value": "application/json" }
    ],
    "query_params": [
      { "name": "expand", "value": "full" }
    ],
    "body": [
      { "name": "domain",       "value": "{{input.domain}}" },
      { "name": "company_name", "value": "{{input.company_name}}" }
    ]
  }
}

Field-by-field:
  - method            HTTP verb. GET, POST, PATCH, PUT, DELETE.
  - endpoint          The URL. Variable references (`{{input.foo}}`,
                      `{{<action_instance_id>.bar}}`) resolve per-row at
                      run time, so you can build per-row URLs like
                      `https://api.example.com/v1/companies/{{input.id}}`.
  - query_params      List of {name, value}. Omit for none.
  - headers           List of {name, value}. Auth and content-type go
                      here; references inside `value` resolve per-row.
  - body              List of {name, value}. Each item becomes a JSON
                      key on the outgoing request body.

Discovering the output schema:

  1. Configure the action with the body above (Configure Action).

  2. Add ONE example row whose inputs exercise the API call:

       POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/rows
       Body: { "rows": [{ ...representative input values... }] }

  3. Run that row:

       POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/run
       Body: { "row_ids": ["<the_example_row_id>"] }

     The worker hits the upstream API and stores the response 
     so it can be inspected for shape on the next call.

  4. Call Get Action Outputs:

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

     The handler reads the captured response, infers a field per top-level
     JSON key, mints stable responses, persists the new schema onto
     the action, and returns the public `outputs[]` array — each entry
     with a ready-to-paste `reference` token. Drop those tokens
     verbatim into downstream actions' Configure Action bodies.

  5. ⚠ Important: the example row from step 3 ran BEFORE the schema
     existed, so its List Rows cell will NOT carry the discovered
     outputs. To get a populated cell for that row, 
     re-run it — Run Rows on the same row_id, 
     or call Run Action (`POST /actions/{action_instance_id}/run`) to run rows
     just for this action. Alternatively delete the example row (Delete Rows) 
     and run fresh rows. From this point on every new run sees the persisted schema 
     and surfaces the outputs in `cells[<this_action>].outputs`.

================================================================================
4. KEY NOTES
================================================================================

- Output schema is discovered, not declared. Until at least one row
  has run the call, the outputs list is empty. Get Action Outputs 
  is the canonical place to read it once data is available — and note 
  the example row used for discovery won't itself surface the typed outputs
  in its cell (it ran before the schema existed); re-run it or use fresh
  rows. See section 3 for the full walkthrough.
- If the upstream API returns an array of objects, the output schema
  is derived from the FIRST item's keys. Per-key types are inferred
  from that one sample (`string` / `number` / `boolean` / `array` /
  `json`, plus `email` / `url` heuristics on strings) and applied to
  every row downstream.
- References inside `endpoint`, header values, query-param values,
  and body item values all resolve per-row, so the same configured
  action can hit a different URL with different headers and body for
  each row of your sheet.
- Auth is yours to wire. Floqer doesn't manage credentials for HTTP
  API Call — put a bearer token / API key in a header, or wire it
  from an upstream input column if it varies per row.
- Response parsing falls back to text when the body isn't valid JSON.
  Non-JSON responses can still be referenced as a single string output
  but the per-key output schema only materialises for JSON bodies.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: row data -> http_api_call (custom API) -> downstream
processing.

================================================================================
6. WHEN TO USE
================================================================================

Use http_api_call for any API not covered by a built-in action.

================================================================================
7. WHEN NOT TO USE
================================================================================

A built-in action exists for the API
  -> use that action — search https://floqer.com/docs/action-catalog.txt for the
     provider name before falling back to a raw HTTP call.

================================================================================

This file is maintained manually. Last updated: 2026-05-06.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt