# APIWeave

> APIWeave is a local-first, open-source (MIT) desktop app for building and
> running visual API test workflows on a node-graph canvas. A workspace can be
> tracked in git and synced through a remote you own — a GitHub or GitLab
> repository, or a bare repository on a drive.

## 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.

## Git sync

- Tracking a workspace writes it to a local git repository as a deterministic
  tree of JSON files, and each change becomes a commit.
- Connect one remote by URL with your own git credentials. The app fetches,
  integrates, and pushes on its own in auto mode; manual mode waits for
  Sync now. It also runs on launch and every five minutes; in manual mode
  those only fetch, to count what is waiting.
- The merge is semantic, by record, node and field. Changes that do not overlap
  are combined in a real merge commit; a field both sides changed differently
  waits for a pick of "Your copy" or "Remote copy".
- The git host decides access. A refused push turns the workspace read-only:
  edits keep committing locally, the remote's commits still come in, and an
  explicit retry still attempts the push.
- The header shows the state in words and an icon — synced, pending, syncing,
  incoming, merge needed, diverged, read-only, or an error — never colour alone.
- Another machine opens the same workspace with "Open from git…" and the same
  URL. Git must be installed; a workspace that stays local does not need it.

## What a repository never holds

- Secret values, their ciphertext, and the secret store
- Run history and response bodies
- User-scoped environments, node presets, agents, and local workflow revisions

Request definitions are written, because they are the workflow.

## Secrets

- A workflow keeps its {{secrets.NAME}} references, so the repository says
  which secrets it needs; CI supplies each value as APIWEAVE_SECRET_<NAME>.
- A credential typed straight into a request or a variable is withheld as
  <SECRET>, or a secret-named header is left out. A value is still sent to the
  API under test by the machine that runs the request.

## Running a repository in CI

- apiweave run ./tests takes the repository folder directly, with no database
  and no git required. Add --project and --env to narrow the run.
- Exit code 0 when everything passed, 1 when a test failed, 2 for a usage or
  configuration error.

## Limits in this release

- One branch per workspace: no branch picker, no branches or pull requests
  created from the app, and no host APIs.
- Environment inheritance and user-scoped environments are not carried into
  the repository.
- A workflow's own version history in the app is not its git history.

## Vocabulary

- Workspace — the unit holding projects, environments, and workflows.
- Project — an ordered group of workflows that run together.
- Environment — the variables a run resolves against.
- Remote — the one git repository a tracked workspace pushes to and fetches
  from.
- Your copy / Remote copy — the two sides of a conflicted field.

## Links

- Product overview and FAQ: https://apiweave.app/
- Git sync guide: https://apiweave.app/guides/git-sync
- Desktop downloads: https://github.com/Kaysharp42/apiweave/releases
- Source: https://github.com/Kaysharp42/apiweave
- Docs: https://github.com/Kaysharp42/apiweave/tree/main/docs