API endpoints

The endpoint and its URL

An endpoint belongs to one item and always runs its latest published version — there are no API versions to manage. Its address is <method> https://<your-waiso-address>/exec/<project-id>/<path>. The project id is the project’s permanent public id (it starts with p_), not its name, so renaming the project never breaks a caller; the path defaults to the item’s folder path and name. A wrong path, or an endpoint that is turned off, answers 404 — the same as a project that does not exist, so nobody can probe for names.

Turn an endpoint on from the item’s Triggers tab (Turn on endpoint), from the publish notice, or on the API page by switching its row’s Status on (clicking an inactive row asks first: Enable & configure). A new endpoint is POST, synchronous, protected by a token, with inputs read from the JSON body. Clicking an active row opens Configure endpoint: Endpoint URL, HTTP Method, Execution Mode, Authentication, Parameter Passing, Limits and Active Tokens.

Sync, async and every answer

A Synchronous endpoint waits for the run (up to 30 seconds) and answers with its result. An Asynchronous endpoint answers 202 {"runId": "…"} at once; then GET /exec/<project-id>/runs/<runId> returns the same shape as a sync answer — poll it until status is no longer queued or running. A sync call that runs past 30 seconds answers 504 with "status": "timeout" and its runId; the run keeps going and can be polled the same way.

{
  "runId": "0f9c2d4e-…",
  "status": "success",
  "flowRunId": null,
  "output": {
    "closed": true,
    "invoices": 128
  },
  "error": null,
  "errorCode": null,
  "durationMs": 412,
  "totalMs": 466
}

Polling an async run

Long work belongs on an asynchronous endpoint. The caller below starts a run and polls every two seconds. This runs on your system — Waiso scripts themselves have no network access.

import os, time, json, urllib.request

BASE = "https://<your-waiso-address>/exec/<project-id>"
HEADERS = {"Authorization": f"Bearer {os.environ['WAISO_TOKEN']}", "Content-Type": "application/json"}

def call(path: str, args: dict) -> dict:
    req = urllib.request.Request(f"{BASE}/{path}", data=json.dumps(args).encode(), headers=HEADERS, method="POST")
    run_id = json.load(urllib.request.urlopen(req))["runId"]          # 202 {"runId": …}
    while True:
        res = json.load(urllib.request.urlopen(f"{BASE}/runs/{run_id}"))
        if res["status"] not in ("queued", "running"):
            return res
        time.sleep(2)

print(call("monthly-close", {"month": "2026-09"}))

Parameters

The request’s values become the item’s inputs by name. With Request body (the default), send a JSON object: {"month": "2026-09", "dryRun": true}. With Query string, send ?month=2026-09&dryRun=true; query values arrive as text and are delivered as the script’s declared types, and a JSON body, if sent too, is merged in. A value that cannot become its declared type, or a missing required parameter, is refused with 422 invalid_parameter before any run exists.

curl -X POST "https://<your-waiso-address>/exec/<project-id>/reports/monthly-close?month=2026-09&dryRun=true" \
  -H "Authorization: Bearer $WAISO_TOKEN"

A flow receives the values as its Start inputs. A flow with a preprocessor gets the whole request instead, so Parameter Passing is not used for it.

Tokens

1. 1
   Open the settings

   On the API page press Settings. The drawer holds Public Docs, Export and API Tokens.

   Generate token
2. 2
   Name it and choose its endpoints

   Give a Token name (unique in the project), an Expiry — 1h, 1d, 7d, 30d, 1y, a custom amount, or Never — and tick the Endpoints this token can call. A token reaches only the endpoints it lists: ticking them all covers today’s endpoints, and a new endpoint needs the token edited.

3. 3
   Copy it once

   Press Generate Token. Copy your token — it will not be shown again. Send it as Authorization: Bearer <token>.

Revoke token stops it at once — callers get 401 token_revoked — and it stays in the list as Revoked. Prefer one token per caller, so revoking one never breaks the others. An endpoint whose Authentication is Public takes no token at all; use that only for data that is truly public.

The received request

Every run started by an endpoint keeps the request that started it. Open the run — on the Runs page, or a flow step’s run detail — and Received request shows its Query, Headers and Body. Copy as cURL gives a command that sends it again; Re-run with this request starts a new run with it at once (Started run #…, marked Re-run of #…) — always asynchronously.

• Requests are kept 30 days (Request expired after 30 days). Bodies are stored up to 1 MB — the run received it whole — and binary bodies are not stored.
• Headers are stored exactly as received, including Authorization. Anyone who can see the run can read them.
• A call refused by the rate limit is stored too, with no run.

The API page and public docs

The API page lists every endpoint with search, All / Active / Inactive chips with counts and a type filter (Scripts, Flows, Scraper). Each row shows Method, Mode, Auth, Limit and the Status switch. The API Overview panel has four cards: Endpoints (active, inactive, total), Usage for Today, 7d (default), 30d or All (calls, success rate, average time), Top endpoints by calls, and Access (active tokens, docs public or private). Settings → Export downloads the endpoints as JSON, a Postman collection, plain text or cURL commands.

Public documentation

Every project has a documentation page at /api-docs/<project-id> listing its active endpoints with their method, URL, parameters, an example and a try it form that takes a Bearer token. By default only signed-in members of the project can open it. Turn on Settings → Public Docs → Enable public docs and anyone with the link can read and try the endpoints — they still need a token to call a protected one.

Limits

• One endpoint per item. A sync call waits at most 30 seconds.
• Calls per minute (1–100,000) is counted per endpoint per clock minute, for every token together. Runs at the same time (1–1,000) makes extra runs wait, never fail. Both are empty by default.
• Every call that starts a run spends credits like any other run; a refused call (401, 404, 422 before running, 429) spends none.