{
  "openapi": "3.0.3",
  "info": {
    "title": "GeniusFlow Federation",
    "version": "1.5.2",
    "description": "Public federation endpoints for agents. Default base URL is the live Vercel origin. No signup. Discovery: /llms.txt or /.well-known/geniusflow.json (tool_adapter). Docs: /docs/AGENT_TOOL_ADAPTER.md, /docs/FEDERATION_SLA.md, /docs/ATTESTATION_PROOF_SHAPE.md. Status: /api/status. proof_shape v1.0.0 field names are frozen under best_effort_vercel."
  },
  "servers": [
    {
      "url": "https://geniusflow-federation.vercel.app",
      "description": "Live federation (best_effort_vercel)"
    }
  ],
  "components": {
    "schemas": {
      "ProofShape": {
        "type": "object",
        "description": "Frozen proof_shape v1 summary (do not rename fields casually).",
        "required": [
          "version",
          "limbs",
          "admitted",
          "failed_limbs",
          "refuse_limb"
        ],
        "properties": {
          "version": {
            "type": "string",
            "enum": [
              "1.0.0"
            ],
            "example": "1.0.0"
          },
          "limbs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "registry_ref",
              "refuse_or_admit",
              "provenance_spine"
            ]
          },
          "admitted": {
            "type": "boolean"
          },
          "failed_limbs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "refuse_limb": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "Proof": {
        "type": "object",
        "description": "Frozen proof v1 detail object on package/verify.",
        "required": [
          "version",
          "admitted",
          "limbs",
          "failed_limbs",
          "refuse_limb",
          "spec"
        ],
        "properties": {
          "version": {
            "type": "string",
            "enum": [
              "1.0.0"
            ]
          },
          "admitted": {
            "type": "boolean"
          },
          "limbs": {
            "type": "object",
            "required": [
              "registry_ref",
              "refuse_or_admit",
              "provenance_spine"
            ],
            "properties": {
              "registry_ref": {
                "type": "object"
              },
              "refuse_or_admit": {
                "type": "object"
              },
              "provenance_spine": {
                "type": "object"
              }
            },
            "additionalProperties": false
          },
          "failed_limbs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "refuse_limb": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": "string",
            "example": "docs/ATTESTATION_PROOF_SHAPE.md"
          },
          "invented_attestation": {
            "type": "boolean",
            "description": "Present on verify; always false (never invent ATTESTED)."
          }
        },
        "additionalProperties": true
      },
      "PackageDispositionResponse": {
        "type": "object",
        "required": [
          "disposition",
          "proof",
          "proof_shape"
        ],
        "properties": {
          "disposition": {
            "type": "string"
          },
          "exhibited_refusal": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "proof": {
            "$ref": "#/components/schemas/Proof"
          },
          "proof_shape": {
            "$ref": "#/components/schemas/ProofShape"
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "required": [
          "proof",
          "proof_shape"
        ],
        "properties": {
          "found": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "proof": {
            "$ref": "#/components/schemas/Proof"
          },
          "proof_shape": {
            "$ref": "#/components/schemas/ProofShape"
          }
        }
      }
    }
  },
  "paths": {
    "/api/dossier": {
      "get": {
        "operationId": "getDossier",
        "summary": "Entity dossier card (claims[] when ledger-backed)",
        "parameters": [
          {
            "name": "entity",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "AAVE_V3"
          }
        ],
        "responses": {
          "200": {
            "description": "Dossier card JSON"
          }
        }
      }
    },
    "/api/report_feed": {
      "get": {
        "operationId": "getReportFeed",
        "summary": "Bundled report feed for an entity",
        "parameters": [
          {
            "name": "entity",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Report feed JSON"
          }
        }
      }
    },
    "/api/cite": {
      "get": {
        "operationId": "getCiteCatalog",
        "summary": "Cite catalog + catalog_hash",
        "responses": {
          "200": {
            "description": "Cite catalog"
          }
        }
      },
      "post": {
        "operationId": "postCitePacket",
        "summary": "One cite packet with package_hash",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cite packet"
          }
        }
      }
    },
    "/api/verify": {
      "get": {
        "operationId": "verifyGroundingGet",
        "summary": "Re-check grounding (source_url + expected)",
        "parameters": [
          {
            "name": "source_url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expected",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verify result + proof_shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "verifyGroundingPost",
        "summary": "Re-check grounding (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verify result + proof_shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/package": {
      "get": {
        "operationId": "packageDispositionGet",
        "summary": "Package disposition (admit/refuse) over claim fields",
        "responses": {
          "200": {
            "description": "Disposition + proof_shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageDispositionResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "packageDispositionPost",
        "summary": "Package disposition over published claim object",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Disposition + proof_shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageDispositionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/darshan": {
      "get": {
        "operationId": "getDarshan",
        "summary": "Public Darshan (refuse/admit samples + provenance rail)",
        "responses": {
          "200": {
            "description": "Darshan JSON"
          }
        }
      }
    },
    "/api/return_wire": {
      "get": {
        "operationId": "getReturnWire",
        "summary": "Consumption acks (deploy-bake + warm ring + optional KV)",
        "responses": {
          "200": {
            "description": "Return-wire acks + durability metadata (survives_cold_start lists)"
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "SLA/status surface (build_id, bake time, health, honest tier)",
        "responses": {
          "200": {
            "description": "Status JSON"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApi",
        "summary": "This OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI 3 JSON"
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcpRpc",
        "summary": "Remote MCP server (streamable HTTP, JSON-RPC 2.0)",
        "description": "Model Context Protocol over streamable HTTP. Stateless: no session header, no SSE stream. Declares the tools capability only; the declaration is also served at /server.json so declared can be compared against actual.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    },
    "/api/a2a": {
      "post": {
        "operationId": "a2aRpc",
        "summary": "A2A JSON-RPC endpoint (SendMessage)",
        "description": "Answers the skills declared on /.well-known/agent-card.json and refuses anything else by name. Stateless: returns a Message, never a Task.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    },
    "/server.json": {
      "get": {
        "operationId": "getMcpServerJson",
        "summary": "MCP registry declaration for this server",
        "responses": {
          "200": {
            "description": "MCP server.json"
          }
        }
      }
    },
    "/.well-known/agent-card.json": {
      "get": {
        "operationId": "getAgentCard",
        "summary": "A2A agent card (unsigned; states that it is unsigned)",
        "responses": {
          "200": {
            "description": "A2A AgentCard JSON"
          }
        }
      }
    },
    "/.well-known/agent-registration.json": {
      "get": {
        "operationId": "getAgentRegistration",
        "summary": "ERC-8004 endpoint-domain proof (empty registrations, named refusal)",
        "responses": {
          "200": {
            "description": "ERC-8004 registration file JSON"
          }
        }
      }
    }
  }
}