← FailMemory home · Dashboard · Quickstart

FailMemory API Reference

Base URL: https://failmemory.dev

All endpoints speak JSON. Timestamps are ISO 8601 UTC.

Authentication

Create a free account at failmemory.dev/signup and send the returned key as a bearer token:

Authorization: Bearer fm_live_your_key_here

The raw key is shown once. FailMemory stores only its SHA-256 hash. Production does not trust caller-asserted wallet or payment headers: X-Signing-Wallet and X-Payment-Amount-Usd are local-development shims only.

Endpoint summary

Public

Authenticated

POST /v1/signup

Create a free account and primary API key.

Request:

{ "email": "developer@example.com" }

Response — 201 Created:

{
  "account_id": "fm_account_<id>",
  "api_key": "fm_live_<secret>",
  "api_key_masked": "fm_live_1234…abcd",
  "mcp_config": {
    "mcpServers": {
      "fail-memory": {
        "command": "npx",
        "args": ["-y", "fail-memory-mcp"],
        "env": {
          "FAIL_MEMORY_API_KEY": "fm_live_<secret>"
        }
      }
    }
  }
}

The response uses Cache-Control: no-store. Save api_key immediately; it cannot be retrieved later.

POST /v1/report

Submit an external-call failure. Authentication is required.

Request:

{
  "method": "POST",
  "url": "https://api.example.com/v1/resource?id=abc123",
  "request_shape_hash": "<64-character sha256>",
  "status_code": 429,
  "error_message": "Too Many Requests"
}

request_shape_hash is the SHA-256 of the value-free JSON body-shape descriptor documented in Normalization. The official MCP server calculates it locally, sends no body values, and uses the same digest for report and lookup. HTTP clients can omit it for endpoint-wide matching.

For compatibility, the server also accepts a raw JSON payload, derives its structural digest in memory, and never persists the body. New clients should compute and send request_shape_hash instead. If both fields are present, they must describe the same structure.

Response — recorded but not promoted:

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

Response — promoted:

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

Repeated reports of the same normalized pattern from one key update that signer's existing evidence; they do not create additional signers.

GET /v1/lookup

Check whether a request pattern is known to fail.

Query parameters:

• method — required HTTP method.
• url — required full URL; normalized server-side.
• request_shape_hash — optional SHA-256 of the value-free request body shape. The official MCP server computes it when its optional payload input is supplied.

Example:

GET /v1/lookup?method=POST&url=https%3A%2F%2Fapi.example.com%2Fv1%2Fresource&request_shape_hash=<sha256>
Authorization: Bearer fm_live_your_key_here

Hit:

{
  "hit": true,
  "hash": "<sha256>",
  "confidence": 0.91,
  "top_failure_modes": ["429", "503"],
  "fail_count": 3,
  "last_seen": "2026-09-01T18:22:00Z",
  "ttl_remaining_seconds": 81234,
  "match_scope": "request_shape",
  "provenance": "organic"
}

match_scope is request_shape for the exact structural match, endpoint for a current-version endpoint-wide fallback, or legacy_endpoint for an unexpired norm-v1 transition hit. The server never returns an expired pattern.

organic means three or more independent signers corroborated the failure. seeded means a first-party probe observed it without independent corroboration yet.

Miss:

{ "hit": false }

Authenticated lookups are free during Seeding. No credit balance is required.

GET /v1/patterns/:hash

Fetch one promoted pattern by hash. Authentication is required. During Seeding, the request is free and does not require a credit balance.

Pattern records include method, url_template, failure/success counts, timestamps, failure modes, TTL, confidence, normalization version, and provenance.

GET /v1/patterns

Bulk export returns:

{ "patterns": [] }

The endpoint currently requires an active account entitlement. Public signup does not create one, and paid Checkout is not live, so normal accounts receive 403 active bulk-export subscription required. Earlier documentation that advertised a purchasable monthly plan was premature.

Credit-ledger endpoints

POST /v1/credits/deposit and GET /v1/credits/balance remain in the API for a future metered stage. They are not part of current customer onboarding, and no public production payment flow is configured around them. Do not send funds based on these endpoints.

GET /metrics

Returns public operational counters including active total, organic, and seeded patterns; report/signing aggregates; and the current service start timestamp. cache_hit_rate_organic_24h is calculated from authenticated lookup hits and misses over the last 24 hours, excluding accounts marked internal. lookup_hits_24h and lookup_misses_24h expose the denominator. The older hit_rate_24h field is retained as an alias for the same real lookup rate.

Promotion and provenance

• Ordinary API-key signers contribute one unit of evidence per normalized pattern. Three independent signers promote it as organic.
• A designated first-party seeder key may promote a pattern as seeded from one observation. The provenance label is always returned on lookup hits.
• Repeating the same report from the same signer increases its occurrence count but never fakes signer diversity.
• MCP reports authenticate with an API key. They contribute evidence without earning the dormant contributor-credit mechanism.