Skip to main content
Create and inspect Journeys, manage related Journeys as a group, and connect a Google spreadsheet through the same account permissions used by the dashboard. The API credential selects the team and source data mode. A livemode field in the request body does not switch that mode.

​
Create a draft and inspect it

Use a test credential for this example. API_BASE_URL is the documented base URL including /v2; GIGSTACK_API_KEY is set locally.
Creation returns HTTP 201 and data.status: "draft". The initial graph can be empty. Read GET /journeys/catalog before constructing a graph: it supplies node keys, configuration fields, allowed source collections, graph rules and limits. Use those keys in graph.nodes[].type and connect nodes through graph.edges. Do not invent action names or assume that a graph accepted as a draft can publish. PUT /journeys/{id} updates only supplied draft fields. It does not replace a published snapshot. For people using Firebase or a personal MCP credential, mutations require the team’s administrator authority. Team API and OAuth credentials use their authorized team scope; their creator is not impersonated.

​
Test, publish and pause

POST /journeys/{id}/test accepts source_collection and exactly one of source_id or source_snapshot. For example, a payments trigger can use an approved synthetic payment ID:
HTTP 201 returns data.run_id, meaning the dry-run was queued. Read GET /journeys/{id}/runs and find that ID to inspect status, steps, and binnacle. The response contains only the latest 50 runs. has_more: true indicates a capped history; this endpoint does not accept a cursor. Once the graph and intended effects have been reviewed, POST /journeys/{id}/publish validates and publishes a version. Publishing enables automation for matching events in that data mode. Test-mode automations can still execute configured actions; test data is not a blanket promise of no notifications or provider calls. POST /journeys/{id}/pause pauses future processing. Read the Journey back to confirm the persisted state. DELETE /journeys/{id} accepts only draft or archived Journeys. POST /journeys/{id}/clone creates another draft. Optional targetLivemode selects the copy’s mode; the source must remain accessible in the credential’s mode. Inspect the returned warnings strings and review destination references before publishing. Cloning does not publish the copy.

​
Edit a group without overwriting another change

Use POST /journey-groups to create a group and one to ten draft Journeys in one operation. Each entry needs its name and complete graph. GET /journey-groups/{id} returns the group fields and its journeys array. Before PUT /journey-groups/{id}, read the group and copy last_updated into the request’s expectedLastUpdated. Send the entire final journeys array: include id to update an existing member; omit id to create one. Existing Journeys missing from this array are archived. An empty array archives every member, so confirm that this is the intended change. The update requires the freshness token unless the group is empty. HTTP 409 group_changed means the group or a child changed. Read it again and review the new diff before proposing an update. Do not retry the old body automatically. POST /journey-groups/{id}/revert uses the same freshness token and restores the previous revision. The response gives revisionId, revertedTo, and per-Journey results. Group publish and pause also return per-Journey results: HTTP 200 can contain failures. Inspect every entry’s status, reason, and errors, then read affected Journeys to establish their actual state.

​
Connect and verify Google Sheets imports

  1. Read GET /sheets and share the spreadsheet with its service_account_email as an Editor.
  2. Connect with POST /sheets/connect using a Firebase or personal MCP credential belonging to a person with direct owner or editor access in Google Drive. Domain, group and link-based access do not establish that person’s authority. Send url, optionally sheet_name, header_row (1–50) and copy_from_other.
  3. Read GET /sheets/fields?target=payment or target=invoice. Use the returned dotted field paths for the mapping. open_objects identifies extensible objects; required_containers identifies required objects without required leaf fields. Fields marked columnOnly must come from a spreadsheet column.
  4. Save the mapping with PUT /sheets/mapping. It contains target, fields, and optionally poll_interval_minutes (2 or 5). Each field binding has column, value, or both; a constant value is the fallback for an empty cell.
  5. Call POST /sheets/preview. Check mapping_error and every row’s errors. Preview validates mapped request bodies; it does not establish that later client lookups, provider calls or fiscal issuance will succeed.
  6. With the effects approved, call POST /sheets/enable. The importer polls the sheet and can create payments or invoices. Saving a changed mapping pauses import, so preview and enable it again deliberately.
  7. Read GET /sheets for sync status and GET /sheets/rows for row outcomes. The latter returns at most 50 recent rows; no cursor is available.
Team API and OAuth credentials can manage an existing connection. They preserve its connecting person; the background importer checks that person’s current permissions. Connecting a new sheet always requires a verified person. Saving or enabling a mapping also requires edit permission for its target module. GET /sheets/headers refreshes cached headers and reads sheet contents; despite being a GET, it is not a pure read. POST /sheets/sync returns HTTP 202 with queued: true; it requests the next poll and does not prove import completion. Use POST /sheets/pause to stop polling. DELETE /sheets disconnects the sheet while retaining its row ledger to avoid recreating previously imported rows. A team can have a connection per data mode, using different spreadsheet tabs. copy_from_other copies an existing mapping and interval; it does not bypass ownership checks. Existing account restrictions still apply.

​
Recover from an uncertain write

After a timeout or server error, inspect the current Journey, group, connection, or row outcomes before issuing another mutation. A failed response can follow a successful write. These operations do not promise a general idempotency key. Keep queued, published, imported, and externally completed outcomes distinct. The contracts and fixtures are checked offline. This guide does not claim that every automation or Google provider path has been exercised in staging.