{
  "openapi": "3.1.0",
  "info": {
    "title": "Felarity Public API",
    "description": "Felarity REST API. Bearer-token auth with per-key scopes, per-key rate limits, and per-call audit rows. Mint keys at https://app.felarity.com/app/settings/ (API keys section).",
    "version": "1.0.0",
    "contact": {
      "name": "Felarity",
      "url": "https://felarity.com/contact/",
      "email": "hello@felarity.com"
    },
    "license": { "name": "Felarity MSA", "url": "https://felarity.com/legal/terms/" }
  },
  "servers": [
    { "url": "https://api.felarity.com/v1", "description": "Production" }
  ],
  "tags": [
    { "name": "verify", "description": "Public attestation verification (no auth)." },
    { "name": "account", "description": "Caller identity and usage." },
    { "name": "workspace", "description": "Workspace metadata." },
    { "name": "reports", "description": "Reports + attestation chains." }
  ],
  "security": [{ "BearerAuth": [] }],
  "paths": {
    "/usage": {
      "get": {
        "tags": ["account"],
        "summary": "Caller usage and rate-limit state",
        "responses": {
          "200": {
            "description": "Usage info",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Usage" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/workspace": {
      "get": {
        "tags": ["workspace"],
        "summary": "Workspace metadata for the caller's bound workspace",
        "responses": {
          "200": {
            "description": "Workspace",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": ["reports"],
        "summary": "List reports for the caller's workspace",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Reports list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ReportSummary" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/reports/{id}": {
      "get": {
        "tags": ["reports"],
        "summary": "Fetch a report with full attestation chain",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Report payload + attestation",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Report" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/verify": {
      "post": {
        "tags": ["verify"],
        "summary": "Verify an exported attestation chain",
        "description": "Public — no authentication required. Returns valid/invalid plus a per-stage breakdown.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SignedChain" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "flrt_*",
        "description": "Mint at https://app.felarity.com/app/settings/. Token shown ONCE on creation."
      }
    },
    "schemas": {
      "Usage": {
        "type": "object",
        "properties": {
          "user_id": { "type": "string" },
          "workspace_id": { "type": "string" },
          "tier": { "type": "string", "enum": ["demo", "starter", "professional", "enterprise"] },
          "rate_limit_per_min": { "type": "integer" },
          "scopes": { "type": "string" }
        }
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "is_phi_eligible": { "type": "boolean" },
          "retention_audio_days": { "type": "integer" },
          "retention_transcript_days": { "type": "integer" },
          "retention_report_days": { "type": "integer" },
          "require_mfa": { "type": "boolean" }
        }
      },
      "ReportSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "session_id": { "type": "string" },
          "industry": { "type": "string" },
          "title": { "type": "string" },
          "signing_key_fingerprint": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "session_id": { "type": "string" },
          "industry": { "type": "string" },
          "title": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "payload": { "type": "object", "additionalProperties": true },
          "attestation": { "$ref": "#/components/schemas/SignedChain" }
        }
      },
      "AttestationNode": {
        "type": "object",
        "properties": {
          "node": { "type": "integer", "minimum": 1, "maximum": 8 },
          "type": { "type": "string", "enum": ["AUDIO_CAPTURE", "TRANSCRIPTION", "CONTRADICTION_DETECTION", "SPEAKER_DIARIZATION", "ATTRIBUTION_BINDING", "ACOUSTIC_ANALYSIS", "TOPOLOGY_ANALYSIS", "FINAL_REPORT"] },
          "prev_hash": { "type": "string" },
          "node_hash": { "type": "string" },
          "timestamp": { "type": "number" },
          "timestamp_iso": { "type": "string", "format": "date-time" }
        }
      },
      "SignedChain": {
        "type": "object",
        "required": ["chain"],
        "properties": {
          "schema_version": { "type": "string", "example": "felarity-attest/1" },
          "chain": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationNode" } },
          "signature": {
            "type": "object",
            "properties": {
              "chain_root": { "type": "string" },
              "signature": { "type": "string", "description": "base64-encoded Ed25519 signature" },
              "algorithm": { "type": "string", "enum": ["ed25519"] },
              "signing_key_fingerprint": { "type": "string", "description": "First 16 hex chars of SHA-256(public_key_raw)" },
              "public_key_pem_url": { "type": "string", "example": "/.well-known/felarity-signing-key.pem" }
            }
          }
        }
      },
      "VerifyResult": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "hash_chain_valid": { "type": "boolean" },
          "signature_valid": { "type": "boolean" },
          "nodes_verified": { "type": "integer" },
          "errors": { "type": "array", "items": { "type": "string" } },
          "chain_root": { "type": "string" },
          "signing_key_fingerprint": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid Bearer token",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "BadRequest": {
        "description": "Invalid request",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found or not visible to caller's workspace",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}