API reference

Weave has two HTTP APIs:

All requests and responses are JSON with Authorization: Bearer <token>. {repoId} is the platform's repository id (returned when you create a repository), never org/name. Workstream names in a path are one URL segment: encode / as %2F.

Authentication#

Check a token with GET https://weave.directory/api/whoami (see Security & access). The server's GET /api/weave/version (no token) answers {"server": "0.4.0"}.

Errors#

Platform: { "error": { "code": "…", "message": "…" } }

Weave server: { "type": "error", "code": "…", "message": "…", "retryable"?: true, "error_id"?: "…" }

Successful stitch requests answer 200 even when the outcome is suggested or rejected: inspect outcome. Every write that appends to the operation log carries entry_id and entry_ids (and the X-Weave-Entry-Id header); POST /undo {"entry": "<id>"} takes it.

Platform: organizations#

POST /api/v1/orgs#

Create an organization; the caller becomes its owner. Scope org:admin; needs a verified email.

{ "name": "Acme", "slug": "acme" }

201:

{ "id": "clx…", "slug": "acme", "name": "Acme" }

The slug is lower-cased and must match ^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$. A taken slug: 409 conflict.

Platform: repositories#

POST /api/v1/orgs/{slug}/repos#

Create a repository. Scope org:admin; the caller must be a member of the organization; a token limited to repositoryIds can't create repositories.

{ "name": "shop", "description": "Our web shop", "private": true, "workstreams": ["preprod"], "template": "empty" }

201:

{ "id": "cm3k…", "name": "shop", "org": "acme", "slug": "acme/shop", "private": true,
  "workstreams": ["main", "preprod"], "warnings": [] }

409 conflict: the name exists, or its storage prefix is still bound. 502 weave_unavailable: the Weave server didn't answer.

POST /api/v1/orgs/{slug}/repos/import#

Create a repository and import a git branch or a zip into main. Scope org:admin.

{ "name": "app", "private": true, "workstreams": ["dev"],
  "source": { "type": "git", "url": "https://github.com/acme/app.git", "ref": "main", "history": true, "maxCommits": 1000, "token": "…" } }

source.type: "zip" takes url and stripRoot. 202 with the repository fields plus import (a job; poll GET /api/weave/{id}/imports/{importId}). workstreams are created once the import is done. If the import can't start, the repository is deleted again.

DELETE /api/v1/repos/{repoId}#

Scope repo:admin, repository admin. Purges the repository on the Weave server (every row, object and search entry), then removes it from the platform. Permanent: ids are never reused and later requests answer not_found. If the purge fails, the repository is kept.

200: { "id": "cm3k…", "deleted": true }

Copy, transfer, archive, export#

• Copy keeps workstream history (same changeset ids, authors, times); the parents of named workstreams always come too. at_head (64 hex) needs exactly one workstream. Not copied: the operation log (the copy starts a new one), claims, pending suggestions, open change requests, webhooks.
• Transfer keeps the repository id. Agent tokens of the old organization that named it are revoked.
• Archive makes the repository read-only on every transport (409 "this repository is archived (read-only); unarchive it to make changes"); reads keep working. Both calls are idempotent.
• Export writes a new gzip tar each call and answers a 15-minute download link; the file is deleted after 7 days.

Workstreams: remove and restore#

The Weave server then allows only the workstream's creator or a repository admin. main → 400; child workstreams → 409 conflict; weaved stitches not promoted → 409 unpromoted_stitches unless force=true; verifier agents → 403. See Workstreams.

Platform: tokens#

scopes is required (1–10 known scopes); expiresInDays 1–365, default 30; repositoryIds ≤ 200. A repository-limited caller's new token inherits its repositories when none are given.

curl -s https://weave.directory/api/v1/tokens -H "Authorization: Bearer $WEAVE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci", "scopes": ["repo:read", "repo:write"], "repositoryIds": ["cm3k…"], "expiresInDays": 90}'

Platform: agents and agent tokens#

Agent = {id, userId: "agent:<id>", name, kind, pathScope | null, disabled, disabledAt, createdAt, activeTokens}. The caller must be an owner or admin of the organization (with 2FA). Details: For AI agents.

Platform: service accounts#

ServiceAccount = {id, name, organizationId, role, disabled, disabledAt, createdById, createdAt, activeTokens}. ServiceToken = {id, name, scopes, repositoryIds, allowedRoutes, expiresAt, lastUsed, createdAt}. All need a person's PAT.

Platform: webhooks#

Repository admins (scope repo:admin; people and service accounts).

Webhook = {id, repositoryId, name, url, events, active, archived, archivedAt, secretSet, createdAt, updatedAt}. The secret is never returned. Events and signing: Webhooks & events.

Platform: attestation keys#

GET|POST /api/v1/orgs/{slug}/attestation-keys and DELETE /api/v1/orgs/{slug}/attestation-keys/{keyId} (scope org:admin) manage organization-wide Ed25519 keys. POST body: {publicKey, label?, types?}. See Attestations.

Weave server: workstreams#

Workstream = {slug, parent, parent_head, synced_parent_head, head, settings: {ownership, inherit}, created_by, created_at, archived_at, archived_by}. main exists implicitly.

Weave server: stitches#

POST /workstreams/{ws}/stitches#

Submit one sealed changeset (the CLI builds and hashes changesets with the shared Rust crate; the server rejects an id that doesn't match its content).

{ "changeset": { "id": "…", "change_id": "…", "base_head": "…", "author": "<your user id>", "agent": null,
                 "intent": "Add cart total", "why": "…", "created_at": "…", "ops": [ … ] },
  "blobs": { "<hash>": "<base64>" }, "allowRevert": false, "allowSecret": [] }

200 {"type": "stitch", "outcome": StitchOutcome}:

{ "outcome": "weaved", "head": "…", "changeset": "…", "carried_forward": false, "duplicate": false,
  "suggestions": [], "change_requests": [], "notices": [] }
{ "outcome": "suggested", "head": "<unchanged>", "suggestions": [ … ] }
{ "outcome": "rejected", "reason": "…", "symbols": [ … ] }

A suggestion routed because of a clash carries clash: {code: "lost_update" | "reverts_newer_work", reason, authors, stitches}. Resending the same changeset never weaves twice (duplicate: true).

POST /workstreams/{ws}/stitches/batch#

Several changesets (1–64) woven in order under one workstream lock with one head update:

{ "stitches": [ { "changeset": { … }, "blobs": {}, "allowRevert": false } ], "allowSecret": [] }

200 {"type": "stitches_submitted", "workstream", "head", "outcomes": [{"submitted", "outcome"}]}. One rejected stitch doesn't fail the others, except later ones that depend on it (code: "depends_on_rejected"). Every changeset's author must be the caller (400 otherwise).

POST /stitch (whole files)#

The simplest way to stitch over HTTP: send whole files and the server diffs them into symbol operations.

curl -s https://api.weave.directory/api/weave/$REPO_ID/stitch \
  -H "Authorization: Bearer $WEAVE_TOKEN" -H "Content-Type: application/json" \
  -d '{"workstream": "dev", "intent": "Fix login copy", "why": "support ticket 41",
       "files": [{"path": "src/app/page.tsx", "content": "…"}, {"path": "old.md", "content": null}],
       "moves": [{"from": "img/a.png", "to": "assets/a.png"}]}'

content: null deletes a file; moves become file moves applied before files. The response is the bare StitchOutcome ("no changes" when nothing differs). Paths under .weave/ are refused, except .weave/decisions/. Send "allowRevert": true when taking back someone's newer change is intended.

Other stitch-related routes#

Weave server: claims and ownership#

Targets are path (whole file) or path::qualified_path, literal (no globs on the wire). To have a write weave directly, write as symbols[i].owner, or as anyone when owner is null.

curl -s https://api.weave.directory/api/weave/$REPO_ID/claims \
  -H "Authorization: Bearer $WEAVE_TOKEN" -H "Content-Type: application/json" \
  -d '{"targets": ["app/[id]/page.tsx", "package.json::scripts.dev"], "feature": "part:p3", "partial": true}'

Weave server: suggestions and change requests#

Weave server: resolution points#

A point is {id, tag, workstream, symbol, copy?, head_side, copy_side, owner, author, callers, other_callers, suggestion, reason, fallback?, state, created_at, resolved_at?, resolver?, why?}. The owner, the current claim holder or a repository admin choose any; the author only head. See Resolution points.

Weave server: messages, notices and events#

Message = {id, from, to, recipients?, body, about?, reply_to?, thread, created_at, read}. Body ≤ 16 KiB, 1–50 addresses. Read access is enough.

Weave server: search#

GET /search?q=&workstream=&limit=&paths=a,b&kinds=function,method or POST /search {query, workstream?, limit?, paths?, kinds?} → {type: "code_search", workstream, head, stale?, indexing?, hits}. GET /search/index shows what is indexed; POST /search/reindex {workstream?, full?, wait?} (admin) backfills. See Search.

Decisions#

Writes are stitches: the response is {type: "stitch", outcome, decision}.

Releases: tags, protection, attestations#

See Decisions & history.

Audit and purges#

See Security & access.

Git import and mirrors#

Repository admins only. A mirror pushes one workstream to one branch of a git remote over HTTPS; every history entry becomes one git commit with the intent and why as the message. An import fills an empty workstream from a git branch (one stitch per commit, first-parent chain) or a zip.

continuous: false is a one-off export. Mirror tokens are stored encrypted and never returned; import tokens are used for the fetch only.

Webhook deliveries#

GET /webhooks/deliveries?status=&webhook=&event=&before=&limit= and POST /webhooks/deliveries/{id}/redeliver (repository admin). See Webhooks & events.