← FailMemory home · Dashboard · Quickstart

FailMemory API Reference

Base URL: https://failmemory.dev

All endpoints speak JSON. All timestamps are ISO 8601 UTC.

HTTP Endpoints

Public (no auth)

Contributor endpoints (identity-gated, see Identity and signed requests)

Consumer endpoints (requires credit balance or API key)

Billing endpoints

No rate limits are enforced at launch. Quality control is handled by the 3-signer promotion threshold (D-028) and PII stripping at write time, not by request-rate caps. This section will be updated when any edge-level limits ship.

Request / Response Contracts

POST /v1/report

Submit a failure report. Free. Requires the X-Signing-Wallet header on every request — see Identity and signed requests below for the v1.0.0 soft-identity shim and the v1.1.0 roadmap toward real cryptographic verification.

Request body:

{
  "method": "GET",
  "url": "https://api.example.com/v1/resource?id=abc123",
  "payload": {},
  "status_code": 429,
  "error_message": "Too Many Requests",
  "reporter_wallet": "0xabc…"
}

reporter_wallet is optional. Anonymous reports are accepted but earn no credits and no reputation. If reporter_wallet is present it MUST match the signing wallet or the request is rejected with 400.

Response — accepted, pattern not yet promoted (200 OK):

{ "accepted": true, "hash": "<sha256>", "credits_earned": 0 }

Response — accepted, pattern promoted (3rd+ unique signer) (200 OK):

{ "accepted": true, "hash": "<sha256>", "credits_earned": 10 }

credits_earned is 10 once the pattern crosses the 3-report threshold (D-028) and the reporter is not over the 1000/day cap (D-027); otherwise 0.

Response — duplicate, already known (200 OK):

{ "accepted": true, "hash": "<sha256>", "credits_earned": 0, "note": "pattern already known, TTL extended" }

Error responses:

Writes are always free. A missing or invalid credit balance must never block a valid POST /v1/report.

GET /v1/lookup

Check whether a request pattern is known to fail.

Query params:

• method — HTTP method
• url — full URL (will be normalized server-side)
• payload_hash — optional sha256 of the request payload (client-side normalized)

Every lookup is billed $0.0005 before the cache is consulted. A miss costs the same as a hit (see Why misses are billed).

Response — hit (200 OK):

{
  "hit": true,
  "hash": "<sha256>",
  "confidence": 0.91,
  "top_failure_modes": ["429", "503"],
  "fail_count": 47,
  "last_seen": "2026-04-09T14:22:00Z",
  "ttl_remaining_seconds": 72400
}

Response — miss (200 OK):

{ "hit": false }

Error responses:

GET /v1/patterns/:hash

Fetch the full pattern record for a known hash. Costs $0.0005 per call.

Response — found (200 OK):

{
  "hash": "<sha256>",
  "method": "get",
  "url_template": "https://api.example.com/v1/resource?id=<id>",
  "fail_count": 47,
  "success_count": 3,
  "last_seen": "2026-04-09T14:22:00Z",
  "first_seen": "2026-04-03T10:11:00Z",
  "top_failure_modes": ["429", "503"],
  "ttl": 86400,
  "confidence": 0.94,
  "norm_version": "norm_v1"
}

Error responses:

GET /v1/patterns

Bulk export of the entire pattern index. Requires an active $29/mo bulk export subscription (D-021). Subscriptions are billed via Stripe (D-023).

Response — subscribed (200 OK): JSON array of pattern records in the same shape as GET /v1/patterns/:hash.

Error responses:

POST /v1/credits/deposit

Deposit prepaid lookup credits. Minimum $1 (D-019). x402/MPP is the rail for credit deposits (D-023).

Error responses:

GET /v1/credits/balance

Fetch the remaining credit balance for a wallet or API key.

Response — 200 OK:

{ "balance_usd": 1.2345, "wallet": "0xabc…" }

Error responses:

GET /health

Liveness check. Always 200 OK with body {"ok":true}.

GET /metrics

Public live metrics. 200 OK with a JSON body. Fields include total pattern count, contributor count, cache hit rate, and uptime. Exact shape is stable enough for dashboard consumption but not part of the frozen contract — scrape gently.

Identity and signed requests

Every POST /v1/report must identify the reporter. In v1.0.0 this is done via an X-Signing-Wallet HTTP header whose value is the wallet claiming the report. At launch the header value is trusted as-is — no cryptographic verification runs against it. This is an explicit, documented trade-off; see D-063 in brief/01-decisions.md for the full reasoning and the v1.1.0 roadmap toward real x402/MPP signature verification. D-058 describes the eventual target state where identity is cryptographically proven; D-063 describes the v1.0.0 reality where identity is header-asserted.

The rules (D-058 mechanics, D-063 v1.0.0 enforcement reality)

1. The signing wallet — the value of the X-Signing-Wallet header — is the identity of record for reputation, credit awards, and the 3-signer promotion counting. Absence of the header returns 401 Unauthorized. The header is not cryptographically verified in v1.0.0.
2. If reporter_wallet is present in the request body, it must match the X-Signing-Wallet header value. Mismatch returns 400 Bad Request.
3. If reporter_wallet is omitted, the report is anonymous. It is still accepted, still counted toward the promotion threshold, and still stripped of PII at write time — but:
   • no credits are earned
   • no reputation is earned
   • three anonymous reports from the same signing wallet count as one toward the 3-signer promotion threshold

What this means in practice at v1.0.0

Because the header is not verified, the 3-signer promotion threshold (D-028) and the reputation system (D-029) operate on soft identities that a motivated actor can forge by submitting reports from multiple fabricated header values. At v1.0.0 launch scale — D-053 two-week validation window, seeder-dominated early corpus, tens-to-hundreds of organic agents at most — the threat is bounded. There are no real consumers paying for patterns to exploit, and the seeder's reputation is controlled. D-063 has a full threat-model discussion; treat early reputation scores as bootstrap signal rather than Sybil-resistant evidence.

Seeder implication

The seeder uses a single signing wallet. It drives raw report volume but cannot promote patterns on its own — any pattern surfaced in /v1/lookup has been confirmed by at least two additional independent signing-wallet values (which may themselves be soft at v1.0.0; see D-063).

v1.1.0 roadmap

Per D-063, the v1.1.0 work is to wire real signature verification in the production branch of extractX402Context — either by completing an in-house verification with viem once Workers compatibility is checked, or by swapping to x402-hono once its Workers-runtime story is confirmed. Once that lands, X402_DEV_MODE flips to "0" in production and the header-trust path is removed. For contributors who cannot run a signing wallet at all, a deposit-and-scoped-API-key flow is under consideration (D-061's v1.1.0 roadmap line).