> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage automations

> Integration guide for Manage automations

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.

```bash theme={null}
set -euo pipefail
created=$(curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/journeys" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Payment follow-up","description":"Draft for review"}')
journey_id=$(printf '%s' "$created" | jq -er '.data.id')
curl --fail-with-body --silent --show-error \
  "$API_BASE_URL/journeys/$journey_id" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY"
```

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:

```json theme={null}
{
  "source_collection": "payments",
  "source_id": "payment_example"
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.