{
  "openapi": "3.1.0",
  "info": {
    "title": "Sourced — hosted corroboration API",
    "version": "1.0.0",
    "description": "Corroboration verdicts for claims: how many DISTINCT INDEPENDENT origins report each claim's event, since when, with receipts. Honest by design: undercounts rather than overcounts, syndicated copies collapse to one origin, single-origin claims stay unlabeled, and it never says 'true'.\n\nTwo tiers:\n- **anonymous** — no key, 60 requests/minute, corroboration is computed within each batch (stateless).\n- **API key** (`Authorization: Bearer sk_src_…`) — 600 requests/minute, a persistent event store (firstSeenAt is real; corroboration accumulates ACROSS requests), and an own hash-chained transparency log whose head is anchored daily into public git history.\n\nKeys are currently issued manually: hello@tickwire.news.\n\nSpec: https://sourced.ink · Proof: https://sourced.network · The `/api/v1/*` paths are frozen — v1 never breaks. (`/api/assess` and `/api/verify` remain as aliases.)",
    "contact": { "email": "hello@tickwire.news", "url": "https://sourced.ink" },
    "license": { "name": "MIT (engine)", "url": "https://github.com/Ryan-hasi/sourced/blob/main/LICENSE" }
  },
  "servers": [{ "url": "https://sourced.run" }],
  "paths": {
    "/api/v1/assess": {
      "get": {
        "summary": "Machine-readable usage summary (includes your tier when a key is sent)",
        "operationId": "assessUsage",
        "security": [{}, { "bearerKey": [] }],
        "responses": { "200": { "description": "Usage document (JSON)." } }
      },
      "post": {
        "summary": "Corroboration verdicts for a batch of claims",
        "operationId": "assess",
        "security": [{}, { "bearerKey": [] }],
        "description": "Anonymous: corroboration within the batch. With a key: the call also reads/writes your persistent event store, so the same event reported by a new origin an hour later STILL corroborates, and firstSeenAt is the true first sighting.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["claims"],
                "properties": {
                  "claims": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "items": { "$ref": "#/components/schemas/Claim" }
                  },
                  "clusters": {
                    "type": "object",
                    "description": "Optional pre-grouping: claim id -> origins reporting that same event in this batch (max 100 origins per entry). Duplicates collapse.",
                    "additionalProperties": { "type": "array", "items": { "type": "string" } }
                  },
                  "config": { "$ref": "#/components/schemas/Config" }
                }
              },
              "example": {
                "claims": [
                  { "id": "a", "title": "Major dam breach reported upstream", "origin": "reuters", "publishedAt": "2026-07-10T21:00:00Z" },
                  { "id": "b", "title": "Major dam breach reported upstream", "origin": "bbc", "publishedAt": "2026-07-10T21:04:00Z" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One verdict per input claim, in input order. null = unassessable claim (passes through unlabeled — never an error). `memory` is \"batch\" (anonymous) or \"persistent\" (keyed).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdicts": {
                      "type": "array",
                      "items": { "oneOf": [{ "$ref": "#/components/schemas/Verdict" }, { "type": "null" }] }
                    },
                    "engine": { "type": "string" },
                    "memory": { "enum": ["batch", "persistent", "volatile (store not provisioned)"] },
                    "honest": { "type": "string" },
                    "config": { "$ref": "#/components/schemas/Config" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "description": "Malformed, unknown, or revoked key. Requests WITHOUT a key are never 401 — anonymous is a supported tier." },
          "405": { "description": "Method not allowed." },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/verify": {
      "post": {
        "summary": "Verify a Sourced transparency chain",
        "operationId": "verifyChain",
        "security": [{}, { "bearerKey": [] }],
        "description": "Recomputes every record hash, back-link and sequence number. For human verification prefer the in-browser receipts at https://sourced.network — this endpoint is for programmatic use.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": { "type": "array", "items": { "$ref": "#/components/schemas/LogRecord" } },
                  "jsonl": { "type": "string", "description": "Alternative: raw JSONL, one record per line." },
                  "payload": { "description": "With seq: check an inclusion proof for this payload." },
                  "seq": { "type": "integer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Valid: { ok: true, length, head, payloadIncluded? } · Broken: { ok: false, badIndex, reason: 'hash mismatch' | 'broken link' | 'sequence gap' }."
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/chain": {
      "get": {
        "summary": "Read a hosted transparency chain (public — that's the point)",
        "operationId": "readChain",
        "parameters": [
          { "name": "chain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The chainId (sha256 of the owning key, truncated — public, unguessable, never reversible)." },
          { "name": "month", "in": "query", "schema": { "type": "string", "example": "2026-07" }, "description": "One monthly bucket of records." },
          { "name": "full", "in": "query", "schema": { "type": "string", "example": "1" }, "description": "The whole history from genesis — what you need to verify." }
        ],
        "responses": {
          "200": { "description": "Without month/full: { chainId, name, seq, head, ts, months }. With: { records: LogRecord[] }." },
          "404": { "description": "Unknown chain or empty month." }
        }
      },
      "post": {
        "summary": "Append to YOUR chain (key required)",
        "operationId": "appendChain",
        "security": [{ "bearerKey": [] }],
        "description": "Commits any JSON payload into your hash-chained log: { payload } → the new LogRecord. Reads are public; writes need the key. Heads are anchored daily into public git history (github.com/Ryan-hasi/sourced/tree/main/anchors) — after that, not even we can rewrite your history unnoticed. Limits: 32 kB payload, 30 appends/minute, 5000 records/month.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["payload"], "properties": { "payload": { "description": "Any JSON — e.g. a digest of the verdict batch you just published." } } } } }
        },
        "responses": {
          "200": { "description": "{ chainId, record: LogRecord, head, public }." },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "description": "Missing/unknown key — chains are writable only by their owner." },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/chains": {
      "get": {
        "summary": "Public directory of all hosted chains",
        "operationId": "listChains",
        "description": "[{ chainId, name, seq, head, ts }] — what the daily anchor workflow reads, and how anyone can independently mirror all heads.",
        "responses": { "200": { "description": "{ chains: [...] }." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer", "description": "API key (sk_src_…). Issued manually for now: hello@tickwire.news." }
    },
    "schemas": {
      "Claim": {
        "type": "object",
        "required": ["id", "title", "origin", "publishedAt"],
        "properties": {
          "id": { "type": "string", "description": "Stable report id; used to look up clusters entries." },
          "title": { "type": "string", "description": "The claim in words — event identity derives from it." },
          "origin": { "type": "string", "description": "The source; the unit of independence. Normalize consistently (always 'reuters', never sometimes 'Reuters UK')." },
          "publishedAt": { "type": "string", "format": "date-time", "description": "Upstream publish time; drives the 'breaking' window. Unparseable disables 'breaking' for this claim only." }
        }
      },
      "Verdict": {
        "type": "object",
        "properties": {
          "corroboration": { "type": "integer", "minimum": 1, "description": "Distinct independent origins for this claim's event — within the batch (anonymous) or across all your requests (keyed)." },
          "corroboratingSources": { "type": "array", "items": { "type": "string" }, "description": "Receipts: the OTHER origins (never the claim's own). Max 6 by default." },
          "firstSeenAt": { "type": "string", "format": "date-time", "description": "Anonymous: the request time. Keyed: the TRUE first sighting across your requests." },
          "signal": { "enum": ["confirmed", "breaking", "developing", null], "description": "Deliberately no 'true' and no veracity score." }
        }
      },
      "Config": {
        "type": "object",
        "description": "Numeric threshold overrides, clamped server-side. Defaults are the honesty contract — tighten freely, loosen knowingly.",
        "properties": {
          "mergeSimilarity": { "type": "number", "default": 0.6, "minimum": 0.3, "maximum": 1 },
          "minSharedTokens": { "type": "number", "default": 3, "minimum": 1, "maximum": 10 },
          "confirmedAt": { "type": "number", "default": 4, "minimum": 2, "maximum": 20 },
          "corroboratedAt": { "type": "number", "default": 2, "minimum": 2, "maximum": 20 },
          "breakingWindowMs": { "type": "number", "default": 1800000, "minimum": 60000, "maximum": 86400000 },
          "receiptsCap": { "type": "number", "default": 6, "minimum": 1, "maximum": 20 },
          "keyTokens": { "type": "number", "default": 8, "minimum": 3, "maximum": 16 }
        }
      },
      "LogRecord": {
        "type": "object",
        "required": ["seq", "ts", "payloadHash", "prevHash", "hash"],
        "properties": {
          "seq": { "type": "integer", "description": "0-based, contiguous." },
          "ts": { "type": "integer", "description": "Epoch ms when appended." },
          "payloadHash": { "type": "string", "description": "SHA-256 hex of the canonicalized payload (keys sorted recursively)." },
          "prevHash": { "type": "string", "description": "Previous record's hash; empty string at genesis." },
          "hash": { "type": "string", "description": "SHA-256 hex over seq|ts|payloadHash|prevHash." }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed envelope. Malformed INDIVIDUAL claims never fail a request — they return null verdicts.",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } }
      },
      "RateLimited": {
        "description": "Per-minute budget exhausted (anonymous: 60/min, keyed: 600/min, chain appends: 30/min). Headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After."
      }
    }
  }
}
