Webpath — API Reference

URL-path-first file hosting where AI agents are the primary clients. The whole surface is plain HTTP — no SDK, no client library, no GUIDs.

Webpath is the spec. knower.cc is an app developed on the Webpath spec — the live reference host. Every example below runs against it.

Mental model

• A space IS a hostname. https://name.knower.cc/ is one space; name.pathwayfs.com another.
• The URL is the storage key. The object key is host + pathname, verbatim. No /api prefix on the data plane, no GUIDs.
• Control plane = data plane. Config, links, audit, stats, the skill file, and the key set are all just files at reserved paths (_config.json, _links.json, _audit, llms.txt, .well-known/).
• No publish step. Visibility is set on write.
• Errors are RFC 7807 application/problem+json with full-sentence, agent-relayable recovery hints in detail.

Auth

Two credentials reach the API — a pth_ key (the day-to-day agent credential) and an owner session (a human signed into their account).

pth_ key — an Ed25519-signed JWT scoped to one space. Send it as a header (keeps it out of logs and history):

Authorization: Bearer pth_…

Browser/link fallback: ?token=pth_… in the URL. Same key, other carrier — but every ?token=/Bearer response is forced Cache-Control: private, no-store and the key is never echoed back, so only hand off a token-in-URL to someone you trust with the key itself. Sending a header and a ?token= that disagree → 400 token-conflict. The public keys that verify pth_ JWTs are served at /.well-known/jwks.json.

Owner session — a cookie (__Host-wp_session, HttpOnly, SameSite=Lax; the legacy __Host-pf_session is still accepted during the transition) proving a human is signed into the account that owns the space. Required for every account-identity action: minting/listing/revoking keys, creating spaces, emergency revoke-all, and reading /api/v1/me. Sign-in mints it via email-OTP (below) and — where a host enables them — passkeys, cross-host SSO, or Cloudflare Access. A session lasts 7 days (8 hours behind an external identity provider).

Sharing with other people is done by email-keyed grants (see Permissions below), not by a distinct token kind — there is no separate share/PAT/subscriber credential.

Accounts — email IS the account (no passwords)

Who am I — GET /api/v1/me

Reflects the session cookie (it deliberately ignores pth_ Bearer keys) so a page's own JavaScript can tell who's looking. It never 401s — anonymous callers just get authenticated:false.

Cache-Control: private, no-store, Vary: Cookie.

What's shared with me — GET /api/v1/me/grants

Reflects the session cookie (same as /me — ignores pth_ keys) and always 200. Lists every path shared with the signed-in account, across all spaces — the data behind a "shared with you" inbox.

Cache-Control: private, no-store, Vary: Cookie.

Data plane — the file verbs

The path is the address. Send the Bearer header.

PUT also accepts ?append / ?prepend as a shorthand for additive writes.

Read query params (GET)

Reads support conditional GET (If-None-Match) and Range. A private file is invisible to a caller without read access: the denial is a byte-identical 404 (never a 403), so an outsider can't even prove the file exists — see Permissions.

Write semantics

• ?visibility=private|unlisted|public sets visibility on write (private is default).
• If-Match / If-None-Match preconditions give compare-and-set (CAS); 412 on mismatch.
• Content-Type is inferred from the extension. Host/space upload policy may restrict file types.
• Read before you overwrite — send If-Match with the ETag you saw.
• Bulk DELETE of a directory/prefix requires ?confirm=<space-hostname>.

Pages & rendering

A clean URL (no extension) is the rendered view; an extension shows source.

GET /<name>        # renders <name>.md to HTML, or serves <name>.html
GET /<name>.md     # raw markdown
GET /<name>.html   # raw HTML
GET /<name>?qr     # QR code of the URL
GET /<name>?og     # social-card image

Markdown supports wikilinks ([[other-page]]), tracked in the links index. Share the clean URL — the result of an agent's work is always a URL, in clean form, no token.

Visibility

Every file carries a visibility, stored on the object and defaulting to private.

Set on write: PUT /page.html?visibility=public. Flip later: PATCH /page.html?meta {"visibility":"public"} — but only the owner or an admin grantee may change visibility (a plain write grant is content-only; see Permissions).

Permissions

Four kinds of caller can touch a space, evaluated in this order — the first that authorizes wins:

1. A pth_ key whose scope covers the request.
2. The owner's session — but only when no key was presented and the request isn't cross-site (see the CSRF stance below).
3. A signed-in grantee — a person the owner shared a path with by email.
4. Anonymous — may read public/unlisted files, and may write into an open drop-box.

How a key is authorized

A key carries a scope. The request is checked against it in this order, and the first failure is the response:

Method → op: GET/HEAD → read, PUT/PATCH → write, DELETE → delete. POST endpoints (version restore, index rebuilds) run their own owner/key gate rather than a generic op. A formats-limited key can only PUT files whose extension is allowed — extensionless paths are refused under such a key.

Owner session vs. key — the CSRF stance

A key always reports its own verdict: presenting any key suppresses the owner-session fallback, so a scoped key never silently inherits owner powers. The session fallback is also suppressed when the request is cross-site (Sec-Fetch-Site: cross-site). Writes are non-simple requests that always preflight, CORS is Allow-Origin: * with no Allow-Credentials, and a __Host- cookie never leaves its origin — so a sibling space can never act as you. Net effect: the session cookie authorizes only same-origin, non-token requests.

What only an owner session can do (no key can): mint/list/revoke keys, create spaces, revoke-all, manage passkeys, read /me. A whole-space write key (paths:["/"]), however, can do everything the owner can on the file & config surfaces — edit _config.json, manage sharing, write _access.json. A key may also carry the admin op — it expands to read+write+delete and simply names that maximal tier (those file/config powers already ride on whole-space write); it grants no owner-session powers.

Revoking keys

• One key: DELETE /api/v1/tokens/:jti denylists that jti until its natural expiry. The minting colo blocks it on the next request; every other colo within ≤60s.
• All keys for a space: POST /api/v1/spaces/:ns/revoke-all bumps the space's key generation, so every key minted before the bump fails instantly and globally (generation is checked against the space record already loaded — no propagation lag). Reach for this the moment a key leaks.

Sharing with people — email-keyed grants

The owner (or an admin grantee, or a whole-space write key) grants access to a path by email, through ?meta:

curl -X PATCH -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/reports/?meta" \
  -d '{"sharing": {
        "bob@example.com": ["read","write"],
        "*": {"ops":["write"], "formats":["md"], "max_size":"1mb"},
        "old@example.com": null
      }}'

• Keys are emails (or "*" = any signed-in account). The email is the account, so the grant is waiting the first time that person signs in.
• Ops are read, write, admin. admin implies read+write+delete and lets the grantee re-share (read/write only — never admin, never to "*"). A plain write grant is an editor: it can create, append/prepend, ?replace, and ?meta, but it is content-only — it cannot change visibility, and deleting needs admin.
• write without read is a drop-box grant: create-only (no overwrites), forced private, honoring optional formats, max_size (≤10 MB), and expires_at. Good for "each named person may leave files here but can't read the others'."
• A grant covers its path and, for a directory (/reports/), everything beneath it — with one floor for "*": a "*" (any-signed-in) directory grant surfaces only public/unlisted children; it never crosses a private child's visibility, or one folder grant would expose every private sibling to everyone with an account. To share private content with any-signed-in, grant the exact path; a named-email directory grant still cascades over private (a deliberate share with a known person). A grant's formats restricts writes, never reads. Set "email": null to revoke that path's grant. Up to 50 entries per PATCH.
• Invite on grant: add "notify": true beside sharing ({"sharing":{…},"notify":true}) to email each freshly-granted named person an invitation — who shared, the URL, what they can do. Never "*" (no inbox), never a removal; omit it and nothing is sent. From the other side, a grantee finds everything shared with them at GET /api/v1/me/grants.
• Grants are consulted only for a signed-in grantee — a presented key always wins, and anonymous traffic never touches the grants table. PATCH ?meta echoes back the current sharing block.

Open drop-boxes — _access.json

To let people write into a directory without naming each one, drop an _access.json in it (control plane = data plane — it's an ordinary file, and it's served public so agents can read the house rules before writing):

{ "write": "anyone", "formats": ["md"], "max_size": "1mb" }

• write is "anyone" (no credential), "keyed" (any live key for this space, whatever its path scope), or "owner"/absent (no ambient grant).
• The nearest _access.json, walking up from the file's directory to the space root, wins.
• Ambient writes are always create-only (a drop box receives, it never lets a stranger clobber), forced private (the owner reviews and flips), plain PUT only (no append/prepend), and bounded by formats + max_size (default 1 MB, hard ceiling 10 MB) plus the host/space upload policy.
• Explicit credentials (owner session, a covering key) are never constrained by the rule — it only widens who may write. Writing _access.json itself needs the owner session or a whole-space write key, and the body is schema-validated (422 bad-access-rule on a typo — a mistake can't silently become a no-grant).

Versioning & history

Every content write is copy-on-write: the prior bytes are kept, so a file's whole history stays browsable and any past state is restorable. There's nothing to opt into — versioning is always on.

• Each PUT, ?append, ?prepend, and in-place ?replace edit creates an immutable version. The response carries an x-version-id header (a ver_… id) plus a version field in the JSON body.
• An identical rewrite (byte-for-byte the same content) is a no-op — no new version.
• A metadata-only change (PATCH /<path>?meta) does not create a version.

History endpoints

The ?versions listing

{
  "path": "/notes.md",
  "current": "ver_…",
  "count": 3,
  "versions": [
    { "version": "ver_…", "created_at": "…", "cause": "put",
      "actor": "…", "size": 812, "current": true,
      "bytes_available": true, "parent": "ver_…", "_links": {} }
  ]
}

cause is one of put · append · prepend · replace · config · drop · pre-existing · delete · restore. A pruned or purged version reports bytes_available:false; a restored one carries restored_from; a tombstone entry is marked deleted.

Restore

POST /<path>?restore=<id> never rewinds — it copies the chosen version's content forward as a new version at the top of history, so history stays linear. It's idempotent when the target is already current. Restore is content-only:

• a live file keeps its current visibility and tags;
• a previously-deleted file comes back private.

Returns { path, version, restored_from, visibility, recreated, url }.

Delete is recoverable

DELETE /<path> writes a tombstone, not an erase. The file 404s afterward, but ?versions and ?restore still work — deleting the wrong file is recoverable. To scrub the bytes of one specific version (say a secret that briefly landed in a file), DELETE /<path>?version=<id> purges just that version's content. It refuses the current version (409) — overwrite it first, then purge the old bytes.

History is private

Reading ?versions or ?version= requires write-or-owner auth — even for a public file. An overwrite that briefly held a secret must not become durable public history. Anonymous history reads → 401.

Retention

The newest 30 versions per file are kept (keep_recent); older versions are pruned automatically, and their bytes_available flips to false.

# every content write returns a version id
curl -sD - -o /dev/null -X PUT --data-binary @notes.md \
  -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md?visibility=public" | grep -i x-version-id
#   → x-version-id: ver_…

# browse the history (needs a write/owner key, even for a public file)
curl -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md?versions"

# read one past version's raw bytes
curl -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md?version=ver_…"

# roll a past version back to the top of history
curl -X POST -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md?restore=ver_…"

# deleted the wrong file? it's recoverable
curl -X DELETE -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md"                # 404s afterward…
curl -X POST   -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/notes.md?restore=ver_…"  # …but restore brings it back (private)

Reserved paths (control plane = data plane)

Every space serves these as files. Most are synthesized on read (never stored, so they can't drift).

Control plane — spaces & keys

Spaces

Keys (scoped pth_ tokens)

Scope (scope object on mint):

• namespaces — the space the key works on (required; must be one you own).
• ops — any of read · write · delete · share · subscribe · admin (default ["read","write"]). admin implies read+write+delete and is the maximal "give-a-key" tier; it still grants no owner-session powers (key minting, space creation, revoke-all stay session-only).
• paths — path prefixes the key is limited to (default ["/"] = whole space; a trailing slash matches the whole subtree).
• formats — optional write-format allowlist (extensions).
• ttl_seconds — 1 hour to 365 days (default 7 days).

Errors (RFC 7807)

{
  "type": "https://muse.as/a/webpath/errors/etag-mismatch",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The file changed since you last read it. Re-read it and retry your write."
}

detail is always a full-sentence, agent-relayable recovery hint. Each type URI resolves to a documentation page — the full set is the Error Types index (e.g. etag-mismatch, out-of-scope, token-revoked).

Quick start

# 1. Join a space (get a key)
curl -X POST https://knower.cc/join -d '{"name":"mydocs"}'
#   → {"space":"https://mydocs.knower.cc/","token":"pth_…", ...}

# 2. Publish a page (visibility on write)
curl -X PUT --data-binary @page.md \
  -H "Authorization: Bearer pth_…" \
  "https://mydocs.knower.cc/page.md?visibility=public"

# 3. Share the clean URL
#   → https://mydocs.knower.cc/page

→ Spec · Build an App · Conformance · Generate a server · Examples · Home