{
  "openapi": "3.1.0",
  "info": {
    "title": "ProofCore M2M Protocol API",
    "description": "Zero-Auth Cryptographic Notarization & Provenance Engine on TON Blockchain.\n\n### Mathematical Algorithm (`proofcore-merkle-v1`):\n1. **Asset Hash:** `H_asset = SHA256(raw_bytes)`\n2. **Deal Hash:** `H_deal = SHA256( (H_assets... + H_meta).encode('utf-8') )`\n3. **Tree Traversal:** For each sibling: `direction == 'left' ? SHA256(sibling + current) : SHA256(current + sibling)` (using lowercase hex string concatenation encoded as UTF-8).\n4. **TON Anchor:** Compare resulting root with `MR: <root>` payload in TON transaction.",
    "version": "0.1.0",
    "contact": {
      "name": "ProofCore Protocol Core Team",
      "url": "https://proofcore.org",
      "email": "sealit@proofcore.org"
    }
  },
  "externalDocs": {
    "description": "ProofCore Official GitHub Repository & Python/LangChain Integrations",
    "url": "https://github.com/ProofCore-Protocol/proofcore/tree/main/integrations"
  },
  "servers": [
    {
      "url": "https://api.proofcore.org",
      "description": "Production API Gateway"
    }
  ],
  "paths": {
    "/api/v0.1/seal": {
      "post": {
        "summary": "Seal AI Generated Content",
        "description": "Hashes text content or CI/CD release manifests on-the-fly (SHA-256), persists the forensic snapshot, and queues it for Merkle Tree batching on TON Blockchain.",
        "operationId": "sealContent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SealRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Content queued for blockchain batching.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SealResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (100 req/hour/IP).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v0.1/proof/{deal_id}": {
      "get": {
        "summary": "Get Proof Manifest & Merkle Path",
        "description": "Returns full cryptographic manifest, Merkle tree traversal siblings, and TON blockchain confirmation.",
        "operationId": "getProofStatus",
        "parameters": [
          {
            "name": "deal_id",
            "in": "path",
            "required": true,
            "description": "UUID of the sealed deal",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cryptographic Manifest retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProofManifestResponse"
                }
              }
            }
          },
          "404": {
            "description": "Deal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/download/{deal_id}": {
      "get": {
        "summary": "Download Offline Evidence ZIP",
        "description": "Returns a self-contained ZIP archive containing the original asset, forensic metadata, JSON manifest, PDF certificate, and offline Python/HTML 3-way match verifier scripts.",
        "operationId": "downloadEvidenceZip",
        "parameters": [
          {
            "name": "deal_id",
            "in": "path",
            "required": true,
            "description": "UUID of the sealed deal",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Binary ZIP Archive Stream",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Deal not found or assets purged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SealRequest": {
        "type": "object",
        "required": ["content"],
        "properties": {
          "content": {
            "type": "string",
            "description": "Raw content to be anchored."
          },
          "agent_id": {
            "type": "string",
            "description": "Declared model or agent identifier (Unauthenticated label in v0.1)."
          },
          "title": {
            "type": "string",
            "description": "Optional title for Explorer card."
          },
          "github_oidc_token": {
            "type": "string",
            "description": "Optional GitHub OIDC token for cryptographic identity verification and rate-limit bypass."
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional HTTP callback URL to be triggered when the Merkle Root is confirmed on the TON Blockchain."
          }
        }
      },
      "SealResponse": {
        "type": "object",
        "required": ["status", "deal_id", "sha256_hash", "verification_url", "citation", "badge_url", "badge_markdown"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["queued"],
            "description": "Immediate ingestion status."
          },
          "deal_id": {
            "type": "string",
            "format": "uuid"
          },
          "sha256_hash": {
            "type": "string",
            "description": "Hex SHA-256 fingerprint of the saved payload."
          },
          "verification_url": {
            "type": "string",
            "format": "uri"
          },
          "citation": {
            "type": "string",
            "description": "Text citation badge.",
            "example": "🛡 ProofCore Integrity Proof: https://proofcore.org/app/4eea9784-2371-4505-8f2f-0b4c5a15a9ec"
          },
          "badge_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the dynamic SVG status badge.",
            "example": "https://api.proofcore.org/api/badge/4eea9784-2371-4505-8f2f-0b4c5a15a9ec"
          },
          "badge_markdown": {
            "type": "string",
            "description": "Ready-to-use Markdown snippet for GitHub READMEs.",
            "example": "[![ProofCore](https://api.proofcore.org/api/badge/4eea9784-2371-4505-8f2f-0b4c5a15a9ec)](https://proofcore.org/app/4eea9784-2371-4505-8f2f-0b4c5a15a9ec)"
          }
        }
      },
      "ProofManifestResponse": {
        "type": "object",
        "required": ["deal_id", "title", "status", "created_at", "protocol"],
        "properties": {
          "deal_id": {
            "type": "string",
            "format": "uuid"
          },
          "protocol": {
            "type": "object",
            "properties": {
              "version": { "type": "string", "example": "1.0" },
              "hash_algorithm": { "type": "string", "example": "sha256" },
              "merkle_scheme": { "type": "string", "example": "proofcore-merkle-v1" }
            }
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["sealed", "anchored_onchain", "cancelled"],
            "description": "Lifecycle state:\n- `sealed`: Hashed and queued in batching pipeline.\n- `anchored_onchain`: Confirmed in TON Blockchain block.\n- `cancelled`: Aborted prior to anchoring."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "merkle_root": {
            "type": "string",
            "nullable": true,
            "description": "64-character lowercase hex Merkle Root."
          },
          "merkle_path": {
            "type": "array",
            "description": "Ordered sibling hashes for offline mathematical traversal.",
            "items": {
              "type": "object",
              "required": ["hash", "direction"],
              "properties": {
                "hash": { "type": "string", "description": "64-character lowercase hex sibling" },
                "direction": { "type": "string", "enum": ["left", "right"] }
              }
            }
          },
          "ton_tx_hash": {
            "type": "string",
            "nullable": true
          },
          "ton_lt": {
            "type": "integer"
          },
          "ton_time": {
            "type": "integer",
            "description": "Unix timestamp of TON block confirmation."
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "filename": { "type": "string" },
                "file_type": { "type": "string" },
                "file_size": { "type": "integer" },
                "sha256_hash": { "type": "string" }
              }
            }
          },
          "forensics": {
            "type": "object",
            "description": "Sanitized public metadata (Declared Agent ID, Timestamps). If a valid OIDC token was provided, this will include 'repository' and 'commit_sha' with identity_status='verified_oidc'."
          },
          "verification_url": {
            "type": "string",
            "format": "uri",
            "example": "https://proofcore.org/app/ab6e3e20-8a9e-4d19-b17e-8a48f58c2be7"
          },
          "citation": {
            "type": "string",
            "example": "🛡 ProofCore Integrity Proof: https://proofcore.org/app/ab6e3e20-8a9e-4d19-b17e-8a48f58c2be7"
          },
          "ton_explorer_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "example": "https://testnet.tonviewer.com/transaction/82c1c7deb3f998605565b63bcee00b132eca9715955a8f15e6ed0b325d29b11e"
          },
          "badge_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the dynamic SVG status badge.",
            "example": "https://api.proofcore.org/api/badge/ab6e3e20-8a9e-4d19-b17e-8a48f58c2be7"
          },
          "badge_markdown": {
            "type": "string",
            "description": "Ready-to-use Markdown snippet for GitHub READMEs.",
            "example": "[![ProofCore](https://api.proofcore.org/api/badge/ab6e3e20-8a9e-4d19-b17e-8a48f58c2be7)](https://proofcore.org/app/ab6e3e20-8a9e-4d19-b17e-8a48f58c2be7)"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}