Mаke

View saved version →

---
name: make-api-shell
description: Use when the user wants data out of (or an action in) a SaaS account through Make without a purpose-built automation — "get my unread emails", "list my Jira tickets" — via a small on-demand scenario wrapping the provider's Make an API Call module or a generic HTTP request.
metadata:
  version: "0.1.7" # x-release-please-version
---

# Make API shells — a reusable API endpoint inside Make

An **API shell** is a three-module on-demand scenario — `scenario-service:StartSubscenario` → the provider's
*Make an API Call* module → `scenario-service:ReturnData` — that takes `path`, `method`, `header`, `qs`,
`body` as inputs and returns the provider's response body. Built once per provider **and connection**, it
turns any Make-connected account into an authenticated HTTP endpoint the assistant can call with
`scenario_run`. It is a transport, not business logic: interpreting the response happens afterwards.

**Ground rules.** A 403 means the whole connection must be re-authorized with every permission — never one
tool. A `content` remark on a result is an instruction, not decoration. Say what you resolved an ambiguous
value to before the call that acts on it. The refusal contract and the rest: `make-scenario-reference`, when
something is refused or no tool seems to fit.

## Workflow

1. **Resolve the anchor before any tool call**: provider (Gmail vs Outlook, HubSpot vs Salesforce, Jira vs
   Linear), and the account or mailbox when several are plausible. Ask only for what is missing.
2. `environment_get` → `organizationId`/`teamId`.
3. **Find the API-call module.** `app_find` with "<provider> make an API call". The module's name is not
   standardized (`makeAnApiCall`, `makeApiCall`, `MakeAPICall`, `ActionMakeAnApiCall`, …) — take it from the
   result, never guess. No Make app for the provider (or only a community one) → build an HTTP shell instead:
   [HTTP fallback](./references/http-fallback.md).
4. `module_spec(schemas: true)` on `["scenario-service:StartSubscenario", "<app>:<apiCallModule>",
   "scenario-service:ReturnData"]`. Note the API-call module's connection requirement and its `mapper` field
   names (`url`, `method`, `headers`, `qs`, `body` — confirm; a few apps differ) and its output field that
   carries the response body (usually `body`).
5. **Connection.** Reuse an id from `connection.existing` when it is the right account; otherwise
   `connection_create` → the user authorizes → `connection_get`. A connection that authenticates but lacks the
   scope for the intended call fails at run time with a provider permission error — treat that as "no suitable
   connection" and request a new one; connections cannot be widened in place.
6. **Reuse an existing shell only for an existing connection.** `scenario_list` with `search` for the shell
   naming convention (`API shell: <app>`), then `scenario_get` to confirm the three modules and
   `scenario_module_get` to confirm which connection the middle module is bound to. A **new connection always
   gets a new shell** — never repoint an existing shell at a different account.
7. `scenario_create` from [api-shell.json](./examples/api-shell.json): `scheduling: {"type": "on-demand"}`,
   the `interface` with the five inputs and one `data` output, and `ReturnData` mapped to
   `{"data": "{{2.body}}"}` — the response body, not the whole bundle `` {{`2`}} `` and not a guessed
   nested field.
8. `scenario_activate`, then a **narrow validation run**: `scenario_run` with
   `inputs: {"path": "…", "method": "GET", "header": [], "qs": [{"name": "limit", "value": "5"}], "body": null}`.
   Read `outputs.data`. A 404 whose URL shows a doubled segment (`/calendar/calendar/v3/…`) means the module's
   base URL already carries that prefix — strip it from `path`.
9. **Then retrieve for real**: list or search with a narrow filter → collect ids → detail calls for the
   shortlist → normalize for the user. Every step goes through the shell; do not fall back to the app's native
   search modules for this workflow family.

Say which phase you are in (provisioning vs retrieval), whether the shell and the connection are reused or
new, and the exact API path you chose for the business question.

## Rules

- **Writes need confirmation.** `POST`/`PUT`/`PATCH`/`DELETE` through a shell mutate the live account: state
  the call and get an explicit yes before running it. Default retrieval is `GET`.
- **Query parameters go in `qs`**, as `[{name, value}]`, never concatenated into `path`. Split a
  `path?x=1` the caller hands you.
- **Empty body on GET.** Some provider modules serialize an empty `body` badly on `GET`/`DELETE`. If a read
  fails only when `body` is present-but-empty, drop the `body` mapping from the middle module (a read-only
  shell) and keep a separate write shell that maps it. `ReturnData` stays unchanged either way.
- **A shell is bound to one app module.** A Gmail shell is not a Google Calendar shell even though both are
  "Google" — different app, module, and connection family. Build one per provider app.
- **Interpret failures by phase.** Connection request problems are provisioning; an activation refusal is the
  shell; an empty or odd payload from a successful run is the API path or the normalization — first check that
  `ReturnData` still maps the middle module's `body`, then the path/method/qs, before touching the blueprint.
  A provider auth or scope error is never fixed by editing the shell — go back to step 5.
- Reading and running a shell needs the same scopes as any scenario; the *provider's* permissions are proven
  only by a successful run of the intended call.

## Not covered here

- Scenarios that run on their own trigger or schedule — `make-scenario-building`.
- Debugging a shell run beyond `scenario_run`'s response — `make-scenario-operations`
  (`scenario_execution_inspect`, `scenario_execution_module_get`).

Referenced files: 3

View saved version →

---
name: make-scenario-building
description: Use when creating a new Make scenario or editing an existing one — finding modules, connections and account-dependent values, wiring the flow, saving through scenario_create or scenario_patch. Not for explaining, running or debugging a scenario, or for API-call shells.
metadata:
  version: "0.1.7" # x-release-please-version
---

# Make scenarios — creating and editing

The tool descriptions carry each tool's rules; this skill carries the order of operations and the decisions
the tools cannot make. A straight-line scenario needs nothing beyond the workflow below. Load a reference only
when its trigger applies.

**Ground rules.** A 403 means the whole connection must be re-authorized with every permission — never one
tool. A `content` remark on a result is an instruction, not decoration. `scenario_create`/`scenario_patch`
make one save each: put everything one change needs in one call, and read a refused write's `errors` as a
free dry run. Say what you resolved an ambiguous value to ("the Sales channel", "next Monday") *before* the
call that acts on it. Details and the refusal contract: `make-scenario-reference`, when something is refused.

## Build a new scenario

1. Pin the design in words the user agrees with: every app by name (ask when they name a category — "email",
   "a form", "AI"), what starts it, what moves where, what happens to non-matching items.
2. `environment_get` → `organizationId`/`teamId`.
3. `app_find` with the user's words, once per goal. Given an instant and a polling trigger for the same
   source, say which you chose and why.
4. `module_spec` for every planned module in one call, `schemas: true` — it gives each module's exact
   `config` shape and its `dynamic` paths.
5. Connections: reuse an id from `connection.existing`; otherwise one `connection_create` for every app,
   hand over the link, `connection_get` when the user says they are done.
6. `module_field_resolve` every `dynamic` path in `dependsOn` order, copying `value` into `config`. A polling
   trigger's start point is the `/data` path — ask "existing items or from now?" before resolving it.
7. Compose the flat list: your ids, one `root: "main"`, everything else `follows` or `parent`, one `config`
   per module, `filter` for a plain continue-or-stop gate. Google Sheets, Gmail, Make AI Tools or date math
   involved → [App gotchas](./references/app-gotchas.md) first.
8. `scenario_create`, `autoActivate` off unless asked. Fix everything in `errors` and resubmit; relay
   `warnings`.
9. Verify, then `scenario_activate`. On-demand: `scenario_run` with `inputs`. Polling/scheduled: activate,
   `scenario_run`, `scenario_execution_get`. Webhook: the *user* sends one real request — `scenario_run`
   does not exercise a webhook. Then give `https://<zone>.make.com/<teamId>/scenarios/<scenarioId>`.

## Edit an existing scenario

1. `scenario_get` for structure and `lastEdit`; `scenario_module_get` (`config: true`) only for the modules
   you will change.
2. Adding modules: `app_find` and `module_spec(schemas: true)` as above; resolve `dynamic` paths against the
   module's current `config`.
3. One `scenario_patch` with `expectedLastEdit` and every operation the change needs. Send only the `config`
   domains you changed. Fix every `{{<id>.field}}` reference a removed or moved module leaves dangling in the
   same call.
4. A module added in a call gets its id on save, so wiring onto it is a second call with the returned
   `lastEdit`. Verify from the response's `modules` echo.

## A webhook whose payload is unknown

`payloadShape: "learned"` in `module_spec`, or a bare `gateway:CustomWebHook`: create with the trigger alone →
the user sends one real request (or `scenario_trigger_learn` first) → `scenario_trigger_inspect` →
`scenario_patch` the rest. Do not activate a webhook scenario whose fields nobody has seen.

## Decisions the tools leave to you

- **Filter vs if-else vs router.** Skip non-matching items and nothing else → `filter`. Non-matching items
  need their own action → `builtin:BasicIfElse` (+ `builtin:BasicMerge` to rejoin). Several arms that may all
  fire → `builtin:BasicRouter`.
- **Do not over-build.** No error handlers, aggregators or variables unless the design needs them.

## References — load only on the trigger

| Trigger | Reference |
|---|---|
| Mapping a trigger's or on-demand input, a whole bundle or an array element; a mapped field came back empty | [Mapping](./references/mapping.md) |
| A value must be transformed (dates, text, arrays, conditionals) | [IML functions](./references/iml-functions.md) |
| More than a straight line: routers, if-else + merge, multi-condition filters, iterating, aggregating | [Flow control](./references/flow-control.md) |
| The scenario is on-demand, calls another scenario, or is called by one or by an agent | [Subscenarios](./references/subscenarios.md) |
| Placing a Make AI Agent module with tools | [AI agents](./references/ai-agents.md) |
| The user asks for retries or fallbacks, or failure/data loss is unacceptable — most scenarios need none | [Error handling](./references/error-handling.md) |
| Finalizing a Google Sheets, Gmail or Make AI Tools config, or a date expression | [App gotchas](./references/app-gotchas.md) |
| A complete `scenario_create` call to pattern from | [Examples](./examples/README.md) |

Referenced files: 16

View saved version →

---
name: make-scenario-explore
description: Use when orienting in a Make account — listing organizations, teams and scenarios, explaining what an existing scenario does, checking connection health, auditing several scenarios. Not for creating, editing, running or debugging.
metadata:
  version: "0.1.7" # x-release-please-version
---

# Make scenarios — orienting and explaining

The read-only path from "what does this account have" to "explain this scenario" — the entry point of almost
every conversation, and the tool of choice for a non-technical question about an automation.

**Ground rules.** A 403 means the whole connection must be re-authorized with every permission — never one
tool. A `content` remark on a result is an instruction, not decoration. Say what you resolved an ambiguous
value to before the call that acts on it. The refusal contract and the rest: `make-scenario-reference`, when
something is refused or no tool seems to fit.

## Start with `environment_get`

Always first, no arguments: every organization and team the connection reaches, including private spaces,
and the `zone` needed for `https://<zone>.make.com/<teamId>/scenarios/<id>` links. An organization-bound
connection sees one organization and a remark counts the rest — mention that only if the user expects
something that is not there.

## Finding a scenario

`scenario_list` returns at most 25, most recently edited first. Omitting `status` returns every status — it
is not a hidden "active only" filter. Its `trigger` is coarse (`instant`/`scheduled`/`on-demand`); the
webhook-vs-polling distinction lives in `scenario_get`. Narrow by name, folder or status rather than paging.
`scenario_folder_list` only when the user refers to a folder. `scenario_list_show` only when they ask to see
the list rendered.

## Explaining one scenario

`scenario_get` is **enough by itself**: every module in flow order, nesting via `parent` (router arms,
if-else branches, error handlers, agent tools), filters, trigger and schedule, connection health, declared
inputs and outputs. It omits each module's `config` on purpose — do not read that as incomplete, and do not
fan `scenario_module_get` across every module. Call `scenario_module_get` (with `config: true`) only when a
specific value is the question: which spreadsheet, what the message says, how a field is computed.

How to read a few fields for a non-technical user:

- **`trigger.kind`** decides what "make it run" means: `webhook` → give a URL to post to; `polling` /
  `scheduled` → it runs on its schedule; `on-demand` → run it directly, the only kind that returns outputs.
- **`connections[].status: "missing"`** covers both deleted and broken — the fix is the same, reconnect the
  app in Make — and it is the most common reason a scenario "stopped working". No other tool surfaces it.
- **`isWaitingOnIncompleteExecutions`** means the scenario runs sequentially and is frozen behind stored
  failed runs: no new data flows until those are resolved in Make (this surface cannot). Different from a
  non-zero `incompleteExecutions` alone, which is informational on a non-sequential scenario.
- **`status: "error"`** carries no reason — Make records none. The cause is in the run history
  (`make-scenario-operations`), never in a guess.
- **`modules[].issues`** are Make's own complaints about a module ("not set up") — usually the direct answer
  to "why won't it activate".

Scenario ids come from `scenario_list` or from a create/patch response; `scenario_get` and
`scenario_module_get` take no `teamId`.

## Account-wide health checks

`scenario_list`'s `status` and `incompleteExecutions` are a cheap first pass, not the answer: `status` only
turns `error` after Make deactivates a scenario for *repeated* failures, so a scenario that started failing
yesterday still reads `active`. **A structural read says nothing about whether recent runs succeeded.** For a
real answer, call `scenario_execution_list` (narrowed to `status: "error"`) for every scenario in scope, then
`scenario_get` on the ones that turn up failures for connection health and issues. With more scenarios than
the 25-row cap, narrow by folder or status and say the sweep is partial.

## Not covered here

- Running, activating, or debugging — `make-scenario-operations`.
- Creating or editing — `make-scenario-building`.

View saved version →

---
name: make-scenario-operations
description: Use when running a scenario, switching it on or off, reviewing or debugging executions, or investigating a webhook that receives nothing. Not for creating, editing or explaining a scenario.
metadata:
  version: "0.1.7" # x-release-please-version
---

# Make scenarios — running and debugging

Everything after a scenario exists: running it, switching it on or off, and the run → inspect → drill-down
chain for a failure. Know `trigger.kind` (from `scenario_get`) before calling `scenario_run` — its behavior
depends on it entirely.

**Ground rules.** A 403 means the whole connection must be re-authorized with every permission — never one
tool. A `content` remark on a result is an instruction, not decoration. Say what you resolved an ambiguous
value to before the call that acts on it. The refusal contract and the rest: `make-scenario-reference`, when
something is refused or no tool seems to fit.

## Running: `scenario_run`

- **on-demand** — runs with `inputs` keyed by the declared input names and returns the declared outputs.
- **polling / scheduled** — runs once now; `inputs` are rejected, nothing is returned, the run lands in
  history.
- **webhook** — **nothing runs**. The response hands back the webhook URL (or names the app event). Do not
  report the scenario as "run"; have the user send a real request and check `scenario_execution_list`.

An inactive scenario refuses with a pointer to `scenario_activate` — new scenarios start inactive. A
`"pending"` status means the run outlived the wait: check `scenario_execution_get` with the `executionId`, do
not assume failure. A rejected `inputs` key comes back naming the declared interface — read it rather than
guessing again. Inputs passed to a scenario with no interface are silently unused; a remark says so — relay it.

## Activating and deactivating

Two separate tools, and an already-satisfied request is success, not an error. An activation refusal almost
always means a module still has a configuration error — `scenario_get`'s per-module `issues` say which.

## History: `scenario_execution_list` → `scenario_execution_get`

The list carries `errorMessage` inline for failed runs — often enough for "did it work, why not" without a
second call. A run started moments ago can lag the list by a few seconds (a remark says so; not data loss).
`scenario_execution_get` is for one run's outcome, outputs and consumption (credits and bytes — usage units,
not money); it has no per-module breakdown, so it answers "did it finish", not "which module broke". The
`_show` twins only when the user wants a rendered timeline or card.

## Debugging a failed run: `scenario_execution_inspect` → `scenario_execution_module_get`

1. **`scenario_execution_inspect`** — overall status and error, plus every module that ran with invocation and
   error counts. Make records **one** error per run (the one that ended it); other failures show only as
   `errorCycles` counts. A **warning** run has no top-level `error` at all — `modules[].errors` is the only
   signal, so never report "no error found" as "nothing went wrong".
2. **`scenario_execution_module_get`** on the suspect module and the `cycle` `inspect` reported (usually 1) —
   the real input and output that module saw. Never pick a cycle independently; a wrong cycle returns
   unrelated data with no warning.
3. Cross-check the current `config` with `scenario_module_get` — but first compare `scenario_get`'s `lastEdit`
   to the run's `startedAt`. If the scenario was edited after the run, what you read is not necessarily what
   ran; say so before attributing the bug.

`…[truncated]` marks a cut payload — text, not JSON to parse. A module with no downstream consumer
(`ReturnData`, `WebhookRespond`, a throw) always reports an empty output here even when correct; the scenario's
own output lives in `scenario_execution_get`'s `outputs`.

## A webhook that "isn't receiving data"

- **`scenario_trigger_inspect`** first: it reports **`queued`** deliveries — requests stored and waiting because
  the scenario is inactive, paused, or rate-limited. A non-zero `queued.count` is the answer to "I sent data
  and nothing happened" far more often than a broken mapping. It also shows the detected structure and recent
  deliveries, and with a `deliveryId` one raw request.
- **`scenario_trigger_learn`** puts the webhook into learning mode: the next request is captured as the
  structure without running the scenario (safe on an active scenario). Give the user the URL and have them
  send one real request.

Withheld payloads (confidential or shared webhooks, bodies over 1 MB, binary) are replaced by a placeholder
and explained in a remark — not "nothing arrived".

## Not covered here

- Editing the scenario to fix what you found — `make-scenario-building`.
- Explaining the scenario without running it — `make-scenario-explore`.

View saved version →

---
name: make-scenario-reference
description: Load when a Make scenario tool answers 403, refuses a write for a reason you cannot explain, or no tool seems to cover the request — the shared conventions of environment_get, scenario_*, app_find, module_spec, module_field_resolve and connection_*.
metadata:
  version: "0.1.7" # x-release-please-version
---

# Make scenario-management tools — reference

This is Make's scenario-management tool surface. The tool descriptions say what each tool does; this skill
says what they all assume. The companion skills carry the four rules a routine task needs; come here when a
tool refuses something, answers 403, or a request seems to need a capability no tool covers — the answer is
often "this surface refuses that on purpose".

## Naming

Every tool is `{subject}_{action}`: `scenario_get`, `scenario_execution_inspect`, `module_spec`. Once you hold
a `scenarioId`, everything you can do with it starts with `scenario_`. A `_show` suffix is a UI twin that
returns byte-identical data and additionally renders a widget — use it only when the user asks to *see*
something, never during multi-step work. Names and schemas are permanent; a breaking change ships as a new
tool, which is why enums read slightly over-provisioned and output schemas are non-strict.

## Scopes: all-or-nothing

One bundle of OAuth scopes gates the whole surface. A connection missing any of them is rejected with 403 on
every request. A 403 therefore never means "this one tool needs more permission" — it means the user has to
reconnect the app and grant everything it asks for.

## Read `content`, not only the structured data

Data rides in `structuredContent`. `content` is empty or a short remark that the data cannot say on its own —
a truncation, an ingestion lag, why a list is empty, "the run is still executing". **Treat every remark as an
instruction.** A remark that explains an absence also says to mention it only if the user seems to be missing
something.

## Two layers, two read tools, one write tool

| layer | what it is | read | write |
|---|---|---|---|
| structure | modules, wiring, filters, trigger, schedule, declared inputs/outputs | `scenario_get` | `scenario_patch` structural operations |
| configuration | one module's `config` (`parameters`, `mapper`, `data`, `flags`, `restore`, …) | `scenario_module_get` | `scenario_patch` `module_config_set`; `scenario_create` items |

`scenario_get` is enough to explain what a scenario does. Call `scenario_module_get` only for the modules
whose values are the actual question — never for every module because the structural read omitted them. The
same restraint applies one level up: answer account-wide questions from `scenario_list`'s own fields and drill
into `scenario_get` for at most a few scenarios the user named or the list flagged.

## The write model: one call, one save

`scenario_create` and `scenario_patch` each make exactly one upstream write, after validating the whole
composed result. There is no draft to stage a multi-step edit in, so **everything one change needs goes in one
call**. A refusal (`errors` array) is a free dry run — nothing was written, every problem came back at once;
fix them all and resubmit. `scenario_patch` also refuses when the scenario changed since the `lastEdit` you
passed: re-read and retry, never guess at what changed.

## What the surface refuses to author, and how to say so

A scenario can *use* things this surface cannot *create*; reads describe them, writes refuse them by name and
point at the Make editor. Relay the refusal as a boundary, not a bug to route around:

- **Data stores and custom IML functions** — readable and debuggable, not creatable.
- **Data structures (UDTs)** — reads work; creating one is not available.
- **Incomplete-execution (DLQ) fix-and-retry** — Make's own UI is the path.
- **The blueprint version a past run executed** — compare `scenario_get`'s `lastEdit` with the execution's
  `startedAt` before blaming the current configuration for an old failure; nothing enforces this for you.
- **Drafts/publish and connection re-authorization** — point at the editor.

Do not extend the list by assumption: app-specific instant triggers, error handlers, agents and subscenarios
*are* supported. When unsure, `module_spec` the module — it reports what the module needs, including whether a
webhook can be created for it.

## State a guess before acting on it

A relative date, "the Sales channel", a scenario named descriptively — when a write or a run would accept
whatever you resolve it to, say what you resolved it to *before* that call, not in the closing summary. Where a
wrong guess is refused for free and the answer comes back (`module_field_resolve`, `scenario_run` naming the
declared interface), resolving first and disclosing after is fine.

## Lists are capped, never paged

`scenario_list`, `scenario_execution_list` and option lists cap at 25 rows and take narrowing filters, not
offsets. Ask a narrower question; do not try to page through hundreds of rows.

## Vocabulary

A team typed `"private"` is a **private space** — Make's term for a member's single-person workspace. "My
personal account/team" means that id; say "private space" back.

## Companion skills

- `make-scenario-explore` — orienting, listing, explaining an existing scenario, account-wide checks.
- `make-scenario-building` — finding modules, connections, creating and editing scenarios.
- `make-scenario-operations` — running, activating, and debugging runs and webhooks.
- `make-api-shell` — a reusable API-call or HTTP scenario used as a retrieval transport into a SaaS account.