{
  "openapi": "3.1.0",
  "info": {
    "title": "Certisyn API",
    "version": "1.0.0",
    "description": "Certisyn's verification, forensics, certificate, and intelligence API. All endpoints share a unified capability namespace (vro.verify, forensics.scan, verify.badge, certificates.issue, intelligence.query, bastion.scan, bastion.continuous). Monthly free allowances are applied automatically; design-partner mode and 90-day trials are honored on every call. See /dashboard/usage for real-time consumption.",
    "contact": {
      "name": "Certisyn Support",
      "email": "support@certisyn.com",
      "url": "https://certisyn.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://certisyn.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.certisyn.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "tags": [
    { "name": "Health", "description": "Liveness + identity probes" },
    { "name": "Verify", "description": "Verification badges and checks" },
    { "name": "Forensics", "description": "Document forensic scans" },
    { "name": "Certificates", "description": "Verifiable certificate minting" },
    { "name": "Intelligence", "description": "Graph-backed intelligence queries" },
    { "name": "Checkout", "description": "Stripe-backed SKU checkout + billing" },
    { "name": "Usage", "description": "Monthly usage and capability roll-up" }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Supabase session token. Obtain by signing in via the Certisyn web UI, or by using the auth endpoints (/api/auth/*) directly."
      },
      "PartnerApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-partner-id",
        "description": "Partner-scoped identifier for server-to-server calls. Pair with an api_key_id (x-api-key header) obtained from /dashboard/api-keys."
      }
    },
    "schemas": {
      "BillingContext": {
        "type": "object",
        "description": "Billing flags stamped on every metered response so the caller can display whether a call was free, trial, or comped.",
        "properties": {
          "was_free": { "type": "boolean" },
          "was_trial": { "type": "boolean" },
          "was_design_partner": { "type": "boolean" },
          "remaining_free": { "type": ["integer", "null"] }
        }
      },
      "CapabilityError": {
        "type": "object",
        "required": ["error", "reason"],
        "properties": {
          "error": { "type": "string" },
          "reason": {
            "type": "string",
            "enum": ["no_actor", "no_entitlement", "quota_exhausted", "error"]
          },
          "remaining_free": { "type": ["integer", "null"] },
          "free_allowance": { "type": ["integer", "null"] }
        }
      },
      "UsageRow": {
        "type": "object",
        "required": ["capability", "used", "free_allowance"],
        "properties": {
          "capability": { "type": "string" },
          "used": { "type": "integer" },
          "free_allowance": { "type": "integer" },
          "remaining_free": { "type": "integer" },
          "exhausted": { "type": "boolean" },
          "billable": { "type": "integer" },
          "free": { "type": "integer" },
          "trial": { "type": "integer" },
          "design_partner": { "type": "integer" }
        }
      }
    }
  },
  "paths": {
    "/api/v1/ping": {
      "get": {
        "tags": ["Health"],
        "summary": "Liveness probe",
        "description": "Unauthenticated server heartbeat. Returns build info + server time. Use this to confirm a network path to Certisyn before sending authenticated traffic.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is live.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "service", "version", "now"],
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" },
                    "version": { "type": "string" },
                    "now": { "type": "string", "format": "date-time" },
                    "region": { "type": "string" },
                    "commit": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/forensics/scan": {
      "post": {
        "tags": ["Forensics"],
        "summary": "Run a forensic scan with chain-of-custody provenance",
        "description": "Accepts multipart/form-data with a `file` field, or JSON with `file_base64`. Returns the full ForensicsReport plus a signed provenance envelope. Capability: forensics.scan.",
        "security": [{ "BearerAuth": [] }, { "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "claim_type": { "type": "string" },
                  "claim_issuer": { "type": "string" },
                  "claim_issued_date": { "type": "string" },
                  "entity_name": { "type": "string" },
                  "vro_id": { "type": "string", "format": "uuid" },
                  "entity_id": { "type": "string", "format": "uuid" },
                  "persist": { "type": "string", "enum": ["true", "false"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan report with provenance and catalog version info."
          },
          "402": {
            "description": "Capability denied — no entitlement or free allowance exhausted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilityError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/verify/badge": {
      "get": {
        "tags": ["Verify"],
        "summary": "Render an inline SVG verification badge (public)",
        "description": "Unbilled SVG rendering for embedding on partner websites. Use POST for a billable, HMAC-attested JSON payload.",
        "security": [],
        "parameters": [
          { "in": "query", "name": "partner_id", "required": true, "schema": { "type": "string" } },
          { "in": "query", "name": "variant", "schema": { "type": "string", "enum": ["verified", "powered-by", "certificate"] } },
          { "in": "query", "name": "theme", "schema": { "type": "string", "enum": ["light", "dark"] } }
        ],
        "responses": {
          "200": { "description": "SVG image." }
        }
      },
      "post": {
        "tags": ["Verify"],
        "summary": "Mint a HMAC-attested verification badge",
        "security": [{ "BearerAuth": [] }, { "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vro_code": { "type": "string" },
                  "entity_name": { "type": "string" },
                  "claim_type": { "type": "string" },
                  "claim_value": { "type": "string" },
                  "target_url": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Minted badge payload with signature and verify_url."
          },
          "402": {
            "description": "Capability denied.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilityError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/certificates/issue": {
      "post": {
        "tags": ["Certificates"],
        "summary": "Issue a durable verifiable certificate",
        "security": [{ "BearerAuth": [] }, { "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["claims"],
                "properties": {
                  "certificate_type": { "type": "string" },
                  "vertical_code": { "type": "string" },
                  "entity_name": { "type": "string" },
                  "entity_id": { "type": "string", "format": "uuid" },
                  "subject_email": { "type": "string", "format": "email" },
                  "vro_code": { "type": "string" },
                  "claims": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["type", "value"],
                      "properties": {
                        "type": { "type": "string" },
                        "value": { "type": "string" },
                        "issuer": { "type": "string" }
                      }
                    }
                  },
                  "expires_at": { "type": "string", "format": "date-time" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Minted certificate with signature + digest."
          },
          "402": {
            "description": "Capability denied.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilityError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/intelligence/query": {
      "post": {
        "tags": ["Intelligence"],
        "summary": "Query the Certisyn intelligence graph",
        "security": [{ "BearerAuth": [] }, { "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entity_name"],
                "properties": {
                  "entity_name": { "type": "string" },
                  "vertical": { "type": "string" },
                  "claim_types": { "type": "array", "items": { "type": "string" } },
                  "include": {
                    "type": "array",
                    "items": { "type": "string", "enum": ["briefs", "signals"] }
                  },
                  "limit": { "type": "integer", "minimum": 1, "maximum": 50 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matched entities + briefs + signals."
          },
          "402": {
            "description": "Capability denied.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilityError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/checkout": {
      "get": {
        "tags": ["Checkout"],
        "summary": "Create a Stripe Checkout Session and 303-redirect",
        "security": [],
        "parameters": [
          { "in": "query", "name": "lookup_key", "schema": { "type": "string" } },
          { "in": "query", "name": "sku_code", "schema": { "type": "string" } },
          { "in": "query", "name": "partner_id", "schema": { "type": "string", "format": "uuid" } },
          { "in": "query", "name": "customer_email", "schema": { "type": "string", "format": "email" } }
        ],
        "responses": {
          "303": { "description": "Redirect to Stripe Checkout." },
          "402": { "description": "Design-partner mode — billing suppressed." },
          "404": { "description": "Unknown SKU." }
        }
      },
      "post": {
        "tags": ["Checkout"],
        "summary": "Create a Stripe Checkout Session (JSON response)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lookup_key": { "type": "string" },
                  "sku_code": { "type": "string" },
                  "vro_code": { "type": "string" },
                  "product": { "type": "string" },
                  "customer_email": { "type": "string", "format": "email" },
                  "partner_id": { "type": "string", "format": "uuid" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Session URL + id." },
          "402": { "description": "Design-partner mode — billing suppressed." }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "tags": ["Usage"],
        "summary": "Monthly usage roll-up for the authenticated caller",
        "security": [{ "BearerAuth": [] }, { "PartnerApiKey": [] }],
        "responses": {
          "200": {
            "description": "Current-month usage per capability.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "month_start": { "type": "string", "format": "date-time" },
                    "actor": {
                      "type": "object",
                      "properties": {
                        "user_id": { "type": ["string", "null"] },
                        "partner_id": { "type": ["string", "null"] }
                      }
                    },
                    "is_design_partner": { "type": "boolean" },
                    "trial_active": { "type": "boolean" },
                    "trial_expires_at": { "type": ["string", "null"], "format": "date-time" },
                    "usage": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/UsageRow" }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Authentication required." }
        }
      }
    }
  }
}