@awesomate/hosting-mcp/skill/awesomate-n8n/references/rest-fallback.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# No MCP tools? The full build loop works over REST

The `awesomate_n8n_*` tools load only when Claude Code starts — a session
that just ran the bootstrap doesn't have them until the app restarts. That
must not block the user's first build: every tool is a thin wrapper over
these endpoints, so the ENTIRE loop (context → inventory → validate → draft
→ test → activate) runs over plain REST. Tell the user a restart will make
this smoother, then build anyway.

## Auth (never echo the token)

Read `~/.awesomate/credentials.json` (Windows:
`%USERPROFILE%\.awesomate\credentials.json`) with a small Node script — it
is JSON: `{ profiles: { <slug>: { pat, apiBase } }, defaultProfile }`. Pick
the profile named by `.awesomate.json`'s `{"account"}` in the project root
if present, else `defaultProfile`, else the sole profile. Send
`Authorization: Bearer <pat>` to `<apiBase>` (default
`https://hub.awesomate.ai`). On macOS/Linux,
`node ~/.claude/skills/awesomate-hosting/scripts/resolve-account.mjs --api`
prints `ACCT/API/PAT` in shell format (NOT JSON). Never print the PAT into
the conversation or logs.

## Reads (any plan, consent-gated server-side)

| What | Endpoint |
|---|---|
| Session context + consent + limits + fingerprint (CALL FIRST) | `GET /api/my-n8n/machine/context` |
| All workflows, node-level summaries | `GET /api/my-n8n/machine/workflows?active=&limit=&offset=` |
| One workflow, full JSON | `GET /api/my-n8n/workflows/:id` |
| Node inventory rollup | `GET /api/my-n8n/machine/nodes` |
| Credential inventory (names/types, never secrets) | `GET /api/my-n8n/machine/credentials` |
| Credential type schema | `GET /api/my-n8n/machine/credentials/schema/:type` |
| `$vars` keys | `GET /api/my-n8n/machine/variables` |
| Datatables (+ rows) | `GET /api/my-n8n/machine/datatables` · `GET …/datatables/:id/rows?limit=` |
| Possibilities brief | `GET /api/my-n8n/machine/possibilities` |
| Executions | `GET /api/my-n8n/workflows/:id/executions` · `GET /api/my-n8n/executions/:execId` |
| Node-by-node execution debug | `GET /api/my-n8n/machine/executions/:execId/debug` |
| Instance KPIs (the health sweep) | `GET /api/my-n8n/kpis` · per-workflow: `GET /api/my-n8n/workflows/:id/kpis` |
| Instance-wide error events, grouped | `GET /api/my-n8n/errors?days=7&limit=` — **pass `days`**, it defaults to 30 |
| Execution/table/DB byte sizes + 24h offenders | `GET /api/my-n8n/machine/storage` |
| AI error-analyzer findings (Pro/Embedded) | `GET /api/my-n8n/machine/findings?limit=` |
| Live node docs + community templates | `POST /api/my-n8n/machine/node-catalog/:tool` — tool ∈ search_nodes, get_node, search_templates, get_template, validate_node, tools_documentation; body = the tool's args (e.g. `{"query":"gmail"}`, `{"nodeType":"n8n-nodes-base.gmail"}`) |

## Writes (Support Plus+, consent + quotas + audit apply identically)

| Action | Endpoint |
|---|---|
| Validate workflow JSON | `POST /api/my-n8n/machine/workflows/validate` `{workflow}` |
| Create inactive `[CLI]` draft | `POST /api/my-n8n/machine/workflows/draft` `{name, nodes, connections, settings?}` |
| Update a draft in place | `PATCH /api/my-n8n/machine/workflows/:id` `{name?, nodes, connections, settings?}` |
| Activate / deactivate | `POST /api/my-n8n/machine/workflows/:id/activate` `{active: true|false}` |
| Test-fire the production webhook | `POST /api/my-n8n/machine/workflows/:id/test-fire` `{payload}` |
| Promote draft → live (webhookIds preserved) | `POST /api/my-n8n/machine/workflows/:id/promote` `{draftId}` (`:id` = LIVE id) |
| Roll a promote back | `POST /api/my-n8n/machine/operations/:operationId/rollback` |
| Delete an inactive draft | `DELETE /api/my-n8n/machine/workflows/:id` |
| Create a datatable (pass workflowId!) | `POST /api/my-n8n/machine/datatables` `{name, columns, workflowId?}` |
| Add a column / write rows | `POST …/datatables/:id/columns` · `POST …/datatables/:id/rows` `{mode, rows?/filter?/data?}` |
| Provision Postgres + n8n credential | `POST /api/my-n8n/machine/pg-credentials` |
| n8n Agents: setup status (call first) | `GET /api/my-n8n/machine/agents/status` |
| n8n Agents: n8n's own description + input schema per relayed tool | `GET /api/my-n8n/machine/agents/tools?name=` |
| n8n Agents: run one n8n agent tool (reads, create/mutate/validate/call/publish…) | `POST /api/my-n8n/machine/agents/call` `{tool, arguments}` |

## Error contract (same as the tools)

- `403 consent_required` + `flag` + `settingsUrl` → relay the link, re-check
  after the user toggles (a null `settingsUrl` means contact support).
- `403 missingScopes` → token predates n8n support — reconnect from
  hub.awesomate.ai/claude.
- `429 quota_exceeded` → the plan's daily cap; stop, don't retry-loop.
- `503 node_catalog_unavailable` → use `references/vendor/` knowledge.
- `404` on a path in this table → check the path against this file
  EXACTLY; do not probe variations. This table is the n8n surface the
  `awesomate_n8n_*` tools wrap — if something is missing from it, the fix is
  to add the verified path here, not to guess at one.

The skill's judgment (six-phase loop, approval gates, testing policy,
never-activate-a-copy) applies unchanged — only the transport differs.