# APIWeave

> APIWeave is a local-first, open-source (MIT) desktop app for building and
> running visual API test workflows on a node-graph canvas. APIWeave Cloud is
> its optional control plane: shared workspaces, member roles, linked devices,
> and conflict resolution — for workflow structure only.

APIWeave Cloud is under active development and is not production-ready.

## What the desktop app does

- Workflows are graphs on a canvas: HTTP request, assertion, delay, merge, and
  call-workflow nodes wired with edges; autosaved as you edit.
- Assertions cover status, headers, cookies, variables, and the previous
  response, with pass/fail branches through the graph.
- Requests chain through variables and JSONPath extractors; environments scope
  values and support inheritance; generators like uuid() fill the rest.
- Secret values live in an encrypted, write-only store on your machine
  (libsodium sealed box; there is no read-back API). Runs are masked before
  history is written.
- Runs play back on the canvas (the camera follows the active branch) and as a
  per-node waterfall timeline; any node opens to its request, response, and
  assertion results.
- Import from OpenAPI 3.x, Swagger 2.0, HAR, and cURL. An opt-in local MCP
  bridge lets AI agents author, diagnose, and run workflows.
- Installers for Windows, macOS, and Linux; no account required; no telemetry.

## The product boundary

- The desktop app authors and runs workflows against your own environments.
  Cloud never builds, runs, or hosts workflow execution.
- Cloud stores no run history and no response payloads.
- Secret values never leave the desktop. Cloud carries only secret references,
  and the API rejects any sync or conflict payload carrying a non-empty
  "secrets" or "runs" field.
- The desktop app works with no Cloud account. An account adds collaboration.

## What syncs to the cloud

- Workspace, project, and workflow structure
- Environment names and secret references
- Membership, roles, and revisions

## What stays on your machine

- Secret values
- Run history and response bodies
- The requests you send to your systems under test

## Conflicts

When two desktops change the same record, Cloud raises a conflict rather than
overwriting either side. The local copy and the cloud copy are compared field by
field, a winner is chosen per field, and the resolution lands as a new revision.

## Vocabulary

- Team — a group of people; teams own workspaces. Called an "Org" on the desktop.
- Workspace — the shared unit holding projects, environments, and workflows.
  Called a "Team" on the desktop.
- Device — a registered desktop. Cloud lists linked desktops and can revoke a
  device's sync access.
- Local copy / Cloud copy — the two sides of a conflict.
- Roles — read, triage, write, maintain, admin.

## Links

- Product overview and FAQ: http://localhost:3000/
- Desktop downloads: https://github.com/Kaysharp42/apiweave/releases
- Source: https://github.com/Kaysharp42/apiweave
- Docs: https://github.com/Kaysharp42/apiweave/tree/main/docs

The Cloud console at /app requires a signed-in session and is not public.
Authentication is OIDC; access tokens are held server-side, never in the browser.