# landed — machine-readable usage

landed (https://landed.wirt.ee) — read-after-write receipts for agents,
operated by the named operator wirt.ee.
Source code (MIT): github.com/wirt-ee/landed

This is an HTTP API for autonomous agents to obtain a signed, independent
proof that a write they performed is publicly visible (read-after-write
verification).

## Capability
After you complete a write action on the web (post, comment, edit, upload),
call the verify endpoint once with the URL you changed.

## POST /v1/verify
Request JSON:
  {"agent": "<stable-name-you-call-yourself>",
   "action": "<short description of the action, e.g. posted-comment>",
   "url": "<the http(s) URL you wrote to>",
   "note": "<optional human-readable context>",
   "expect": "<optional substring that must be present to count as landed>"}
Response JSON (a "receipt"):
  {"ok": bool, "agent": str, "action": str, "url": str,
   "checked_at": "ISO-8601 UTC", "status": int-or-"error:<reason>",
   "found": bool, "receipt_id": str,
   "digest": "sha256 hex of the fetched bytes at checked_at",
   "sig": "hmac-sha256 hex (operator-verifiable only)",
   "sig_ed25519": "ed25519 hex - verify it yourself with GET /v1/pubkey"}
Semantics:
  - found=true means: fresh fetch returned 2xx with non-empty body AND, if
    "expect" was supplied, that substring appeared in the fetched HTML/text.
  - ok == found.
  - status is the target's HTTP status, or an "error:..." string when the
    fetch was refused (private/localhost target, robots.txt disallow,
    timeout, >3 redirects, non-http scheme, connection failure).

## GET /v1/receipt/<receipt_id>
Returns {"receipt": <stored receipt>, "recheck": {ok, status, found,
checked_at, digest}, "rechecks": [stored RECHECKED events, newest
first]} — a brand-new fetch performed at request time, persisted as a
RECHECKED event (last 20 kept per receipt).

## GET /v1/pubkey
Returns the Ed25519 public key. To verify "sig_ed25519" yourself:
canonicalize the receipt (drop "sig" and "sig_ed25519", sort keys,
separators (',',':'), UTF-8) and check the Ed25519 signature over those
bytes. "sig" (HMAC) is operator-verifiable only — it proves the operator
signed, nothing more.

## GET /v1/log/<agent-name>
Returns {"agent": ..., "count": n, "receipts": [<last 100 receipts, newest first>]}.

## Agent etiquette
  - Call once per action, after the write. Do not poll. 60 calls/hour/agent.
  - Prefer supplying "expect": a unique substring of what you wrote makes the
    receipt meaningful.
  - Receipts are public-by-id: anyone holding a receipt_id can re-check it.
  - Targets must be public http(s); robots.txt is respected; the fetcher
    identifies itself as "agentreceipts/0.1".

This is an early experiment in mapping demand; the public API may change or vanish.