{
  "openapi": "3.1.0",
  "info": {
    "title": "Proofestry API",
    "version": "0.1.0",
    "summary": "Pay-per-call trust layer for AI agents (x402, USDC)."
  },
  "servers": [
    {
      "url": "https://api.proofestry.dev",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/pricing": {
      "get": {
        "tags": [
          "discovery"
        ],
        "summary": "Price list",
        "operationId": "getPricing",
        "responses": {
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pricing"
                }
              }
            }
          }
        }
      }
    },
    "/v1/scan/metadata": {
      "post": {
        "tags": [
          "scan"
        ],
        "summary": "Scan a file's metadata for privacy risks",
        "description": "Lists EXIF, XMP and PNG text metadata with a risk rating. MCP tool: `scan_metadata`. Price: 0.002 USDC per file.",
        "operationId": "scanMetadata",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FileRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataScan"
                }
              }
            }
          }
        },
        "x-mcp-tool": "scan_metadata",
        "x-price-usdc": "0.002"
      }
    },
    "/v1/scan/provenance": {
      "post": {
        "tags": [
          "scan"
        ],
        "summary": "Detect provenance and AI-generation signals",
        "description": "Reads and validates C2PA manifests (signature and hashes), IPTC DigitalSourceType, and generator metadata. Flags stripped, invalid or conflicting credentials. Reports signals and confidence, never a definitive 'not AI-generated'; the C2PA signer is not yet checked against the trust list. MCP tool: `detect_provenance`. Price: 0.002 USDC per image.",
        "operationId": "detectProvenance",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FileRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvenanceScan"
                }
              }
            }
          }
        },
        "x-mcp-tool": "detect_provenance",
        "x-price-usdc": "0.002"
      }
    },
    "/v1/requests": {
      "post": {
        "tags": [
          "feedback"
        ],
        "summary": "Request a missing tool",
        "description": "Free. MCP tool: `request_missing_tool`.",
        "operationId": "requestMissingTool",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolRequestReceipt"
                }
              }
            }
          }
        },
        "x-mcp-tool": "request_missing_tool",
        "x-price-usdc": "0"
      }
    }
  },
  "components": {
    "schemas": {
      "C2paSummary": {
        "properties": {
          "validation_state": {
            "type": "string",
            "enum": [
              "Trusted",
              "Valid",
              "Invalid",
              "unreadable"
            ],
            "title": "Validation State",
            "description": "Valid: signature and hashes verify. Invalid: tampered or broken. unreadable: a manifest exists but can't be parsed."
          },
          "signature_valid": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Signature Valid"
          },
          "assertions_intact": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Assertions Intact",
            "description": "False when the file no longer matches the signed hashes."
          },
          "issues": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Issues",
            "description": "C2PA validation failure codes (excluding signer trust)."
          },
          "signer_trust": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "trusted",
                  "untrusted",
                  "not_evaluated"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Signer Trust",
            "description": "not_evaluated until the C2PA trust list is configured."
          },
          "signer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Signer"
          },
          "signed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Signed At"
          },
          "claim_generator": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Claim Generator"
          },
          "digital_source_types": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Digital Source Types"
          },
          "software_agents": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Software Agents"
          },
          "claims_ai_generation": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Claims Ai Generation"
          },
          "ai_in_history": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ai In History",
            "description": "Any earlier manifest in the edit history claims AI generation."
          },
          "edited": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Edited"
          },
          "manifest_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Manifest Count"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          }
        },
        "type": "object",
        "required": [
          "validation_state"
        ],
        "title": "C2paSummary"
      },
      "FileRequest": {
        "properties": {
          "file_base64": {
            "type": "string",
            "title": "File Base64",
            "description": "Base64-encoded file bytes (max 4 MiB)."
          }
        },
        "type": "object",
        "required": [
          "file_base64"
        ],
        "title": "FileRequest"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "MetadataFinding": {
        "properties": {
          "field": {
            "type": "string",
            "title": "Field"
          },
          "value": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Value"
          },
          "risk": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ],
            "title": "Risk"
          },
          "reason": {
            "type": "string",
            "title": "Reason"
          }
        },
        "type": "object",
        "required": [
          "field",
          "risk",
          "reason"
        ],
        "title": "MetadataFinding"
      },
      "MetadataScan": {
        "properties": {
          "format": {
            "type": "string",
            "title": "Format",
            "description": "Detected container: jpeg, png or unknown."
          },
          "has_exif": {
            "type": "boolean",
            "title": "Has Exif"
          },
          "has_xmp": {
            "type": "boolean",
            "title": "Has Xmp"
          },
          "has_c2pa": {
            "type": "boolean",
            "title": "Has C2Pa"
          },
          "overall_risk": {
            "type": "string",
            "enum": [
              "none",
              "low",
              "medium",
              "high"
            ],
            "title": "Overall Risk"
          },
          "findings": {
            "items": {
              "$ref": "#/components/schemas/MetadataFinding"
            },
            "type": "array",
            "title": "Findings"
          },
          "note": {
            "type": "string",
            "title": "Note"
          }
        },
        "type": "object",
        "required": [
          "format",
          "has_exif",
          "has_xmp",
          "has_c2pa",
          "overall_risk",
          "findings",
          "note"
        ],
        "title": "MetadataScan"
      },
      "Pricing": {
        "properties": {
          "currency": {
            "type": "string",
            "title": "Currency"
          },
          "network": {
            "type": "string",
            "title": "Network"
          },
          "tools": {
            "additionalProperties": {
              "additionalProperties": {
                "type": "string"
              },
              "type": "object"
            },
            "type": "object",
            "title": "Tools"
          }
        },
        "type": "object",
        "required": [
          "currency",
          "network",
          "tools"
        ],
        "title": "Pricing"
      },
      "ProvenanceScan": {
        "properties": {
          "format": {
            "type": "string",
            "title": "Format"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "ai_generation_signalled",
              "provenance_present",
              "conflicting_signals",
              "credentials_invalid",
              "no_signals_found"
            ],
            "title": "Verdict"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "title": "Confidence",
            "description": "Reliability of the strongest signal, not a claim about the content."
          },
          "signals": {
            "items": {
              "$ref": "#/components/schemas/ProvenanceSignal"
            },
            "type": "array",
            "title": "Signals"
          },
          "c2pa": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/C2paSummary"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present when the file carries a C2PA manifest."
          },
          "flags": {
            "items": {
              "type": "string",
              "enum": [
                "stripped_credentials_suspected",
                "invalid_credentials",
                "conflicting_signals"
              ]
            },
            "type": "array",
            "title": "Flags"
          },
          "stripped_credentials_suspected": {
            "type": "boolean",
            "title": "Stripped Credentials Suspected"
          },
          "limits": {
            "type": "string",
            "title": "Limits",
            "description": "Absence of signals never proves content is not AI-generated."
          }
        },
        "type": "object",
        "required": [
          "format",
          "verdict",
          "confidence",
          "signals",
          "stripped_credentials_suspected",
          "limits"
        ],
        "title": "ProvenanceScan"
      },
      "ProvenanceSignal": {
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "c2pa_manifest",
              "iptc_digital_source_type",
              "generator_name_in_metadata",
              "remote_manifest_reference"
            ],
            "title": "Type"
          },
          "present": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Present"
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Value",
            "description": "Signal value: validation state, source type, generator name or URL."
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source",
            "description": "Where a generator name was found: xmp, exif or png:<key>."
          },
          "ai": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ai"
          },
          "claims_ai_generation": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Claims Ai Generation"
          },
          "validated": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Validated",
            "description": "True when the C2PA signature and hashes verify."
          }
        },
        "type": "object",
        "required": [
          "type"
        ],
        "title": "ProvenanceSignal"
      },
      "ToolRequest": {
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 2000,
            "title": "Description",
            "description": "The tool you wish existed."
          }
        },
        "type": "object",
        "required": [
          "description"
        ],
        "title": "ToolRequest"
      },
      "ToolRequestReceipt": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          }
        },
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "title": "ToolRequestReceipt"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "type"
        ],
        "title": "ValidationError"
      },
      "ResponseValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "ResponseValidationError"
      }
    }
  }
}