{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Source of Truth registry API",
    "version": "2026-07-12",
    "description": "The public record of the AI agent economy: an append-only provenance and evidence registry. Reads anonymous; the only write path is POST /v1/records (token AND signature).",
    "license": {
      "name": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "https://aisourceoftruth.com"
    }
  ],
  "paths": {
    "/r/{digest}": {
      "get": {
        "summary": "Resolve a record",
        "parameters": [
          {
            "name": "digest",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "record"
          },
          "404": {
            "description": "not found"
          },
          "451": {
            "description": "sealed"
          }
        }
      }
    },
    "/a/{content_hash}": {
      "get": {
        "summary": "Asset page",
        "parameters": [
          {
            "name": "content_hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "asset"
          }
        }
      }
    },
    "/v1/records": {
      "get": {
        "summary": "Search records",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "publisher",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "results"
          }
        }
      },
      "post": {
        "summary": "Ingest a record (the only write path)",
        "description": "Requires a Tier-2 token with publish:* scope AND a record signature. Idempotency-Key required. Max 1048576 bytes.",
        "responses": {
          "201": {
            "description": "appended"
          },
          "401": {
            "description": "unauthorized or bad signature"
          },
          "403": {
            "description": "insufficient scope"
          },
          "413": {
            "description": "payload too large"
          },
          "422": {
            "description": "invalid record or digest mismatch"
          }
        }
      }
    },
    "/v1/publishers": {
      "post": {
        "summary": "Register a publisher + key",
        "responses": {
          "201": {
            "description": "registered"
          }
        }
      }
    },
    "/v1/verify-batch": {
      "post": {
        "summary": "Batch verify up to 1000 digests",
        "responses": {
          "200": {
            "description": "results"
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "summary": "Append-only event feed",
        "responses": {
          "200": {
            "description": "events"
          }
        }
      }
    },
    "/v1/stats/popular": {
      "get": {
        "summary": "Most looked up (reporting, not ranking)",
        "responses": {
          "200": {
            "description": "popular"
          }
        }
      }
    },
    "/oauth/register": {
      "post": {
        "summary": "RFC 7591 Dynamic Client Registration",
        "responses": {
          "201": {
            "description": "client"
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "summary": "client_credentials token",
        "responses": {
          "200": {
            "description": "token"
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "summary": "Token-signing public keys",
        "responses": {
          "200": {
            "description": "jwks"
          }
        }
      }
    }
  }
}