{
  "openapi": "3.1.0",
  "info": {
    "title": "SourceVerify API",
    "description": "Trust layer for the Internet — real-time verification of digital artifacts (text, image, video, audio, documents).\n\n**Base URL:** `https://api.sourceverify.app/v1/`\n\n**Authentication:** Bearer JWT via `Authorization: Bearer <token>` for user-context requests, or `X-Api-Key` for machine-to-machine access.\n\n**Core flow:** Producers register artifacts → SHA-256 hash + metadata in Postgres, bytes in S3, verification JSON pinned to IPFS, proof tuple `(contentHash, CID, verdict, modelVersion, timestamp)` anchored on-chain.\n\n**Rate limiting:** 100 requests/minute per IP in production.",
    "version": "0.1.0",
    "x-ai-hints": {
      "authentication": "Use X-Api-Key header for machine-to-machine. Use Bearer JWT for user-context requests (obtain via POST /v1/auth/login).",
      "pagination": "List endpoints accept ?page=1&perPage=20. Follow the next cursor in the response envelope for full traversal.",
      "proof_model": "Each Verification produces a Proof tuple (contentHash, CID, verdict, modelVersion, timestamp). CID is on IPFS via Pinata; the tuple is anchored on-chain via viem.",
      "idempotency": "POST endpoints are not idempotent. Re-submitting an artifact creates a new Verification row.",
      "destructive_operations": [],
      "recommended_first_call": "GET /v1/version"
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT issued by POST /v1/auth/login"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "API key for machine-to-machine integration"
      }
    },
    "schemas": {}
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness probe",
        "tags": [
          "health"
        ],
        "description": "Returns 200 if the API process is up.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/v1/version": {
      "get": {
        "summary": "Build metadata",
        "tags": [
          "version"
        ],
        "description": "Returns the running build version, git SHA, and environment.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "gitSha": {
                      "type": "string"
                    },
                    "env": {
                      "type": "string",
                      "enum": [
                        "development",
                        "test",
                        "production"
                      ]
                    }
                  },
                  "required": [
                    "version",
                    "gitSha",
                    "env"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/register": {
      "post": {
        "summary": "Register a new producer or consumer account",
        "tags": [
          "auth"
        ],
        "description": "Creates a new user account. Not yet implemented.",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/v1/auth/login": {
      "post": {
        "summary": "Exchange credentials for a JWT bearer token",
        "tags": [
          "auth"
        ],
        "description": "Returns a JWT used as `Authorization: Bearer <token>`. Not yet implemented.",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/v1/auth/refresh": {
      "post": {
        "summary": "Refresh an expired JWT",
        "tags": [
          "auth"
        ],
        "description": "Exchanges a refresh token for a new access token. Not yet implemented.",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/v1/auth/logout": {
      "post": {
        "summary": "Invalidate the current session",
        "tags": [
          "auth"
        ],
        "description": "Server-side invalidation of refresh tokens. Not yet implemented.",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/v1/verifications/": {
      "get": {
        "summary": "List verifications scoped to the authenticated user",
        "tags": [
          "verifications"
        ],
        "description": "Paginated list of verification records owned by the caller. Not yet implemented.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "post": {
        "summary": "Submit an artifact for verification",
        "tags": [
          "verifications"
        ],
        "description": "Accepts an artifact (or reference to one in S3) and runs the verification pipeline. Not yet implemented.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/v1/verifications/{id}": {
      "get": {
        "summary": "Fetch a single verification by ID",
        "tags": [
          "verifications"
        ],
        "description": "Returns the verification record together with its IPFS CID and on-chain proof tuple. Not yet implemented.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.sourceverify.app",
      "description": "Production"
    },
    {
      "url": "http://localhost:3001",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "auth",
      "description": "Sign-up, sign-in, refresh, sign-out"
    },
    {
      "name": "verifications",
      "description": "Submit and inspect artifact verifications"
    },
    {
      "name": "health",
      "description": "Liveness and readiness probes"
    },
    {
      "name": "version",
      "description": "Build metadata"
    }
  ]
}