{
 "openapi": "3.0.3",
 "info": {
  "title": "Latavis API",
  "description": "The Latavis API: private credit and the other Latavis verticals through one vertical gateway,\nthe formula and agent surface, deals, accounts and compliance.\n\nCommercial real estate (the CRE E0-E9 engine routes) is not a Latavis offering (pending decision\n2026-10-20): those routes are not documented here and answer 404 (CRE-OFF,).\n\n## Authentication\n- API Key: `X-API-Key` header (required for authenticated endpoints)\n- JWT Token: `Authorization: Bearer <token>` header (alternative auth method)\n- Session Cookie: `session_token` cookie (for browser-based clients)\n\n## Rate Limiting\n- Default: 60 requests/minute per API key\n- Burst: Some endpoints have lower limits (e.g., /predict: 10 req/min)\n- Rate limit status: Check `X-RateLimit-Remaining`, `X-RateLimit-Reset` response headers\n\n## Credit System (S21)\n- Each request consumes credits based on tier and endpoint\n- Tiers: explorer, professional, institutional, enterprise\n- Monthly credit limits defined per tier (see TIER_CREDIT_LIMITS in auth module)\n\n## Response Format\n- All responses are JSON\n- Every error response is one line of JSON with `error` (one line) and `code` (machine-readable); see ErrorBody\n- Successful responses include data payload\n",
  "version": "1.0.0",
  "contact": {
   "name": "Vision Global",
   "email": "api-support@visionglobal.ai"
  },
  "license": {
   "name": "Proprietary",
   "url": "https://visionglobal.ai/license"
  }
 },
 "servers": [
  {
   "url": "https://latavis.com",
   "description": "Latavis (paths under /api/v1; the /api/latavis prefix also works)"
  }
 ],
 "components": {
  "securitySchemes": {
   "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "API key for authentication"
   },
   "BearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "JWT token authentication"
   },
   "SessionCookie": {
    "type": "apiKey",
    "in": "cookie",
    "name": "session_token",
    "description": "Session cookie for browser clients"
   }
  },
  "schemas": {
   "ErrorResponse": {
    "type": "object",
    "required": [
     "error",
     "detail"
    ],
    "properties": {
     "error": {
      "type": "string",
      "description": "Error code or message"
     },
     "detail": {
      "type": "string",
      "description": "Detailed error description"
     },
     "request_id": {
      "type": "string",
      "description": "Request ID for tracking"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Error timestamp"
     }
    }
   },
   "RateLimitInfo": {
    "type": "object",
    "properties": {
     "X-RateLimit-Limit": {
      "type": "integer",
      "description": "Maximum requests allowed"
     },
     "X-RateLimit-Remaining": {
      "type": "integer",
      "description": "Requests remaining in current window"
     },
     "X-RateLimit-Reset": {
      "type": "integer",
      "description": "Unix timestamp when limit resets"
     }
    }
   },
   "MacroStressIndex": {
    "type": "object",
    "properties": {
     "cbsa_code": {
      "type": "string"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     },
     "stress_level": {
      "type": "number",
      "format": "double"
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "sub_indices": {
      "type": "array",
      "items": {
       "type": "number"
      }
     }
    }
   },
   "RegimeOutput": {
    "type": "object",
    "properties": {
     "cbsa_code": {
      "type": "string"
     },
     "regime": {
      "type": "string",
      "enum": [
       "expansion",
       "peak",
       "contraction",
       "trough"
      ]
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "EngineOutput": {
    "type": "object",
    "properties": {
     "engine": {
      "type": "string",
      "enum": [
       "e0",
       "e1",
       "e2",
       "e3",
       "e4",
       "e5",
       "e6",
       "e7",
       "e8",
       "e9"
      ]
     },
     "cbsa_code": {
      "type": "string"
     },
     "asset_class": {
      "type": "string"
     },
     "value": {
      "type": "number",
      "format": "double"
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "PaginatedResponse": {
    "type": "object",
    "properties": {
     "items": {
      "type": "array"
     },
     "total": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     }
    }
   },
   "AlertRule": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "condition": {
      "type": "string"
     },
     "threshold": {
      "type": "number"
     },
     "enabled": {
      "type": "boolean"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Alert": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "cbsa_code": {
      "type": "string"
     },
     "severity": {
      "type": "string",
      "enum": [
       "low",
       "medium",
       "high",
       "critical"
      ]
     },
     "message": {
      "type": "string"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "TenantConfig": {
    "type": "object",
    "properties": {
     "tenant_id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "branding": {
      "type": "object",
      "properties": {
       "logo_url": {
        "type": "string"
       },
       "primary_color": {
        "type": "string"
       },
       "company_name": {
        "type": "string"
       }
      }
     }
    }
   },
   "TenantApiKey": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "key_hash": {
      "type": "string"
     },
     "tier": {
      "type": "string"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "rotated_at": {
      "type": "string",
      "format": "date-time"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "User": {
    "type": "object",
    "description": "the one user object, answered by POST /auth/login (user) and GET /auth/me (user). permissions are the role's RBAC grants. An API-key caller has no user record: id is the key's owner, email is null unless the owner is an address, created_at and last_login are null.",
    "required": [
     "id",
     "email",
     "role",
     "tenant_id",
     "auth_method",
     "mfa_verified",
     "mfa_enabled",
     "mfa_enrolment_required",
     "permissions",
     "created_at",
     "last_login"
    ],
    "properties": {
     "id": {
      "type": "string",
      "nullable": true
     },
     "email": {
      "type": "string",
      "format": "email",
      "nullable": true
     },
     "role": {
      "type": "string",
      "enum": [
       "admin",
       "analyst",
       "viewer"
      ]
     },
     "tenant_id": {
      "type": "string",
      "nullable": true
     },
     "auth_method": {
      "type": "string",
      "enum": [
       "session",
       "api_key"
      ]
     },
     "mfa_verified": {
      "type": "boolean",
      "description": "THIS session passed a second factor (the token's mfa claim;)."
     },
     "mfa_enabled": {
      "type": "boolean",
      "description": "The account has an authenticator enrolled."
     },
     "mfa_enrolment_required": {
      "type": "boolean",
      "description": "An administrator session that must enrol before it can reach anything but enrolment and sign-out."
     },
     "permissions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "last_login": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    },
    "additionalProperties": false
   },
   "ErrorBody": {
    "type": "object",
    "required": [
     "error",
     "code"
    ],
    "description": "Every 4xx/5xx body: one line of JSON, a one-line human `error` and a machine `code`.",
    "properties": {
     "error": {
      "type": "string",
      "description": "One line of plain English: the reason."
     },
     "code": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{1,63}$",
      "description": "Machine-readable reason (e.g. no_such_route, unknown_vertical, route_retired)."
     }
    },
    "additionalProperties": true
   }
  },
  "responses": {
   "BadRequest": {
    "description": "Invalid request parameters",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "Unauthorized": {
    "description": "Authentication failed or missing credentials",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "Forbidden": {
    "description": "Insufficient permissions (RBAC denied)",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "NotFound": {
    "description": "Resource not found",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "TooManyRequests": {
    "description": "Rate limit exceeded",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "InternalServerError": {
    "description": "Internal server error",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   }
  }
 },
 "paths": {
  "/health": {
   "get": {
    "summary": "Server health check",
    "description": "Public endpoint for monitoring server availability and basic health status.",
    "operationId": "getHealth",
    "tags": [
     "Health"
    ],
    "security": [],
    "responses": {
     "200": {
      "description": "Server is healthy",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "engines": {
          "e0": "string",
          "susceptibility": "string",
          "alert": "string",
          "e1": "string",
          "e2": "string",
          "e3": "string",
          "e4": "string",
          "e5": "string",
          "e6": "string",
          "e7": "string",
          "e8": "string",
          "e9": "string"
         },
         "auth_enabled": true,
         "auth": {
          "stack": "string",
          "degraded": false,
          "cause": null,
          "permitted_by": null,
          "features_offline": []
         },
         "accounts_store": {
          "backend": "string",
          "reason": "string",
          "stores": [],
          "rate_limits": "string",
          "persistence_flag": "string"
         },
         "route_families_disabled": [],
         "optional_import_failures": [],
         "data_snapshot": {
          "status": "string",
          "reason": "string",
          "asof_by_source": null,
          "built_at": null,
          "object": null,
          "as_of": null,
          "age_days": null,
          "built_age_days": null
         },
         "freshness": {
          "status": "string",
          "evaluated_on": "string",
          "products": {
           "private_credit": {
            "label": "string",
            "as_of": "string",
            "max_age_days": 0,
            "age_days": 0,
            "alert": true,
            "source": "string",
            "surfaces": [],
            "status": "string",
            "stale_on": "string"
           },
           "macro": {
            "label": "string",
            "as_of": null,
            "max_age_days": 0,
            "age_days": null,
            "alert": true,
            "source": "string",
            "surfaces": [],
            "status": "string"
           },
           "commodities": {
            "label": "string",
            "as_of": null,
            "max_age_days": 0,
            "age_days": null,
            "alert": false,
            "source": "string",
            "surfaces": [],
            "status": "string"
           },
           "cre": {
            "label": "string",
            "as_of": null,
            "max_age_days": 0,
            "age_days": null,
            "alert": false,
            "source": "string",
            "surfaces": [],
            "status": "string"
           },
           "banks": {
            "label": "string",
            "as_of": null,
            "max_age_days": 0,
            "age_days": null,
            "alert": false,
            "source": "string",
            "surfaces": [],
            "status": "string"
           }
          },
          "stale": [],
          "unmeasured": [
           "string"
          ],
          "basis": "string"
         },
         "ready": {
          "ready": true,
          "warm_status": "string",
          "required": [
           "string"
          ],
          "pending": [],
          "failed": [],
          "elapsed_seconds": 0
         },
         "serving_bundle": {
          "status": "string",
          "reason": "string"
         },
         "email": {
          "provider": "string",
          "delivers": false
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "timestamp": {
           "type": "string",
           "format": "date-time"
          }
         }
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/health",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/documents/upload": {
   "post": {
    "summary": "Upload and extract document",
    "description": "Upload PDF or DOCX files for extraction, analysis, and comparison.",
    "operationId": "postDocumentUpload",
    "tags": [
     "Documents"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "file": {
          "type": "string",
          "format": "binary"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Document uploaded and extracted",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "document_id": {
           "type": "string"
          },
          "extracted_text": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "201": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "document_id": 0,
         "filename": "string",
         "file_type": "string",
         "schema": "string",
         "vertical": "string",
         "document_type": "string",
         "word_count": 0,
         "text_preview": "string",
         "extraction": {
          "schema": "string",
          "vertical": "string",
          "document_type": "string",
          "detection": {
           "is_credit_agreement": true,
           "evidence": [
            "string"
           ]
          },
          "fields": {
           "document_title": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "agreement_date": {
            "value": "string",
            "unit": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "borrower": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "administrative_agent": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "collateral_agent": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "portfolio_manager": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "benchmark": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "applicable_margin_pct": {
            "value": 0,
            "unit": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string",
            "note": "string"
           },
           "maturity_date": {
            "value": "string",
            "unit": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string",
            "note": "string"
           },
           "governing_law_state": {
            "value": "string",
            "unit": null,
            "source_text": "string",
            "offset": 0,
            "method": "string"
           },
           "reinvestment_period_end": {
            "value": "string",
            "unit": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string",
            "note": "string"
           },
           "total_commitment_usd": {
            "value": 0,
            "unit": "string",
            "method": "string",
            "source_text": null,
            "offset": null
           }
          },
          "facilities": [
           {
            "name": "string",
            "amount_usd": 0,
            "unit": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string"
           }
          ],
          "covenants": [
           {
            "name": "string",
            "test": null,
            "threshold_text": null,
            "value": null,
            "unit": null,
            "missing_reason": "string",
            "source_text": "string",
            "offset": 0,
            "method": "string"
           }
          ],
          "provenance": {
           "source": "string",
           "text_sha256": "string",
           "as_of": "string",
           "as_of_basis": "string",
           "verification_level": "string",
           "level_name": "string",
           "method": "string"
          },
          "word_count": 0
         },
         "persistence": "string",
         "warning": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/documents/upload",
      "role": "analyst",
      "skip_live": false,
      "body": {
       "filename": "ck0001916099-ex10_1.htm",
       "content_base64": "<the Diameter EX-10.1 fixture>"
      }
     },
     "status": 201,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/documents/{id}/summary": {
   "get": {
    "summary": "Document extraction summary",
    "description": "Get extraction summary and metadata for an uploaded document.",
    "operationId": "getDocumentSummary",
    "tags": [
     "Documents"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Document summary",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "document_id": {
           "type": "string"
          },
          "file_name": {
           "type": "string"
          },
          "extracted_text": {
           "type": "string"
          },
          "key_metrics": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "document_not_found"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/documents/987654/summary",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/documents/compare": {
   "get": {
    "summary": "Multi-document comparison",
    "description": "Compare multiple documents and extract differences and commonalities.",
    "operationId": "getDocumentCompare",
    "tags": [
     "Documents"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "ids",
      "in": "query",
      "required": true,
      "description": "Comma-separated document IDs",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Comparison result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "comparison": {
           "type": "object"
          },
          "differences": {
           "type": "array"
          },
          "commonalities": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "missing": [
          0
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "document_not_found"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/documents/compare?ids=1,2",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/config": {
   "get": {
    "summary": "Tenant branding configuration",
    "description": "Returns tenant branding and configuration settings.",
    "operationId": "getTenantConfig",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Tenant configuration",
      "content": {
       "application/json": {
        "example": {
         "tenant_id": null,
         "tenant_name": "string",
         "tier": null,
         "white_label_enabled": false,
         "branding": {
          "company_name": "string",
          "logo_url": null,
          "favicon_url": null,
          "primary_color": "string",
          "accent_color": "string",
          "bg_primary": "string",
          "bg_secondary": "string",
          "page_title": "string",
          "support_email": "string",
          "support_url": null
         },
         "resolved_via": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/TenantConfig"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/tenant/config",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin": {
   "get": {
    "summary": "Tenant admin overview",
    "description": "Returns overview of tenant administration dashboard.",
    "operationId": "getTenantAdmin",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Tenant admin overview",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tenant_id": {
           "type": "string"
          },
          "users": {
           "type": "integer"
          },
          "api_keys": {
           "type": "integer"
          },
          "usage": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_tenants"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/tenant/admin",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin/branding": {
   "put": {
    "summary": "Update tenant branding",
    "description": "Update tenant branding colors, logo, and company name.",
    "operationId": "putTenantBranding",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "logo_url": {
          "type": "string"
         },
         "primary_color": {
          "type": "string"
         },
         "company_name": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Branding updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TenantConfig"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_tenants"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "PUT",
      "path": "/tenant/admin/branding",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/account/keys": {
   "get": {
    "summary": "List my personal API keys",
    "description": "FE-025. The signed-in user's OWN keys (prefix and usage only; the full key is never returned after creation). Requires a user session; an API key cannot manage keys.",
    "operationId": "getMyKeys",
    "tags": [
     "Account"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "The caller's personal keys"
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "manage_own_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/account/keys",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Create a personal API key",
    "description": "FE-025. Mints a key owned by the signed-in user (\"user:<user_id>\"); the owner is never taken from the body. The full key is returned once.",
    "operationId": "postMyKey",
    "tags": [
     "Account"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "description": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Key created (shown once)"
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "manage_own_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/account/keys",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/account/keys/{id}": {
   "delete": {
    "summary": "Revoke one of my personal API keys",
    "description": "FE-025. Only the caller's own keys; anything else answers 404.",
    "operationId": "deleteMyKey",
    "tags": [
     "Account"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Key revoked"
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "404": {
      "description": "No personal key with that suffix"
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "manage_own_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "DELETE",
      "path": "/account/keys/987654",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/password-reset/request": {
   "post": {
    "summary": "Request a password reset link (public)",
    "description": "ACCOUNTS. 202 with the same answer for known and unknown addresses when a delivering email provider is configured; 503 code=email_unavailable (no link sent, contact support) when it is not. Throttled per address and per IP.",
    "operationId": "requestPasswordReset",
    "tags": [
     "Auth"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "202": {
      "description": "Link sent if the account exists"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_email"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/password-reset/request",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/password-reset/confirm": {
   "post": {
    "summary": "Set a new password with a reset token (public)",
    "description": "ACCOUNTS. Single-use, 1-hour token. Revokes every older session.",
    "operationId": "confirmPasswordReset",
    "tags": [
     "Auth"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string"
         },
         "new_password": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "503": {
      "description": "Accounts store or email provider unavailable (body says whom to contact)",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string",
         "support_email": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "accounts_store_unavailable"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/password-reset/confirm",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/token/inspect": {
   "post": {
    "summary": "Describe a one-time link token without spending it (public)",
    "description": "ACCOUNTS. Returns purpose (password_reset/invite/verify_email), email and expiry, or 400 invalid_token.",
    "operationId": "inspectAccountToken",
    "tags": [
     "Auth"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "503": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string",
         "support_email": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "accounts_store_unavailable"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/token/inspect",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/invite/accept": {
   "post": {
    "summary": "Accept an invitation by choosing a first password (public)",
    "description": "ACCOUNTS. Single-use, 7-day token. Also confirms the email address.",
    "operationId": "acceptInvite",
    "tags": [
     "Auth"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string"
         },
         "new_password": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "503": {
      "description": "Accounts store or email provider unavailable (body says whom to contact)",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string",
         "support_email": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "accounts_store_unavailable"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/invite/accept",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/verify-email/request": {
   "post": {
    "summary": "Email me a confirmation link (signed in)",
    "description": "ACCOUNTS. 503 email_unavailable when no provider is configured.",
    "operationId": "requestEmailVerification",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/verify-email/request",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/verify-email/confirm": {
   "post": {
    "summary": "Confirm an email address with a token (public)",
    "description": "ACCOUNTS. Single-use, 48-hour token.",
    "operationId": "confirmEmailVerification",
    "tags": [
     "Auth"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "503": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string",
         "support_email": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "accounts_store_unavailable"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/verify-email/confirm",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/admin/users": {
   "get": {
    "summary": "List accounts (admin)",
    "description": "ACCOUNTS. Accounts with status (active/invited/deactivated) and email-confirmed flag; never a password hash. Includes whether email delivery is configured.",
    "operationId": "listUsers",
    "tags": [
     "Admin"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "503": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string",
         "support_email": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "accounts_store_unavailable"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/admin/users",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Invite a user (admin)",
    "description": "ACCOUNTS. Creates a password-less account and emails a set-password link; with no email provider the one-time link is returned to the admin (email_sent=false). 409 if the address already has a password.",
    "operationId": "inviteUser",
    "tags": [
     "Admin"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string"
         },
         "role": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "201": {
      "description": "Invited"
     },
     "409": {
      "description": "Account already exists"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_email"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/admin/users",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/admin/users/reset-link": {
   "post": {
    "summary": "Issue a password reset link for a user (admin)",
    "description": "ACCOUNTS. Emails a 24-hour reset link, or returns it to the admin when email is not configured (email_sent=false).",
    "operationId": "adminResetLink",
    "tags": [
     "Admin"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "201": {
      "description": "Link issued"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_email"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/admin/users/reset-link",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/admin/users/deactivate": {
   "post": {
    "summary": "Deactivate or reactivate a user (admin)",
    "description": "ACCOUNTS. active=false deactivates and signs out every session; active=true reactivates.",
    "operationId": "setUserActive",
    "tags": [
     "Admin"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string"
         },
         "active": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_email"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/admin/users/deactivate",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/account/keys/{id}/rotate": {
   "post": {
    "summary": "Rotate one of my personal API keys",
    "description": "ACCOUNTS. Mints a successor key (shown once); the old key keeps working for a 24-hour grace window, then stops.",
    "operationId": "rotateMyKey",
    "tags": [
     "Account"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "201": {
      "description": "Successor key created"
     },
     "409": {
      "description": "Key already in its grace window"
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "manage_own_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/account/keys/987654/rotate",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin/keys": {
   "get": {
    "summary": "List tenant API keys",
    "description": "Returns list of all API keys for the tenant.",
    "operationId": "getTenantKeys",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "API keys list",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedResponse"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/tenant/admin/keys",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Create tenant API key",
    "description": "Create a new API key for the tenant with optional rotation schedule.",
    "operationId": "postTenantKey",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "tier": {
          "type": "string"
         },
         "expires_in_days": {
          "type": "integer"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "API key created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TenantApiKey"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/tenant/admin/keys",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin/keys/{id}": {
   "delete": {
    "summary": "Revoke tenant API key",
    "description": "Revoke an API key permanently.",
    "operationId": "deleteTenantKey",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Key revoked",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_keys"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "DELETE",
      "path": "/tenant/admin/keys/987654",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin/usage": {
   "get": {
    "summary": "Tenant usage statistics",
    "description": "Returns detailed usage statistics for the tenant.",
    "operationId": "getTenantUsage",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Tenant usage stats",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total_requests": {
           "type": "integer"
          },
          "credits_used": {
           "type": "integer"
          },
          "credits_limit": {
           "type": "integer"
          },
          "requests_by_endpoint": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_tenants"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/tenant/admin/usage",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/tenant/admin/users": {
   "get": {
    "summary": "List tenant users",
    "description": "Returns list of users in the tenant organization.",
    "operationId": "getTenantUsers",
    "tags": [
     "Tenant Administration"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Tenant users list",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedResponse"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_tenants"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/tenant/admin/users",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/cs/churn-warnings": {
   "get": {
    "summary": "Churn early warnings",
    "description": "Returns list of customers at risk of churning with warning signals.",
    "operationId": "getChurnWarnings",
    "tags": [
     "Customer Success"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Churn warnings",
      "content": {
       "application/json": {
        "example": {
         "churn_warnings": [],
         "count": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/PaginatedResponse"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/cs/churn-warnings",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/cs/expansion-signals": {
   "get": {
    "summary": "Expansion signal candidates",
    "description": "Returns list of customers showing signals of willingness to expand usage.",
    "operationId": "getExpansionSignals",
    "tags": [
     "Customer Success"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Expansion signals",
      "content": {
       "application/json": {
        "example": {
         "expansion_signals": {
          "tier_limit_explorers": [],
          "power_users": [],
          "full_chain_heavy": [],
          "credit_utilization_high": []
         },
         "count": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/PaginatedResponse"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/cs/expansion-signals",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/usage": {
   "get": {
    "summary": "Customer credit usage",
    "description": "Returns credit usage for the authenticated customer.",
    "operationId": "getUsage",
    "tags": [
     "Usage & Admin"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Usage statistics",
      "content": {
       "application/json": {
        "example": {
         "tier": "string",
         "month": "string",
         "credits_used": 0,
         "credits_limit": 0,
         "credits_remaining": 0,
         "usage_history": [
          {
           "month": "string",
           "credits_used": 0
          }
         ],
         "history_total": 0,
         "history_limit": 0,
         "history_offset": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "credits_used": {
           "type": "integer"
          },
          "credits_limit": {
           "type": "integer"
          },
          "requests_today": {
           "type": "integer"
          },
          "tier": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_usage"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/usage",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/dashboard": {
   "get": {
    "summary": "Admin dashboard data",
    "description": "Returns aggregated platform statistics for administrators.",
    "operationId": "getAdminDashboard",
    "tags": [
     "Usage & Admin"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Admin dashboard",
      "content": {
       "application/json": {
        "example": {
         "current_month": "string",
         "active_keys_by_tier": {},
         "current_month_credits": 0,
         "usage_trend": [],
         "top_customers": [],
         "revenue_projection": {
          "monthly_revenue": 0,
          "annual_revenue": 0,
          "by_tier": {}
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "total_customers": {
           "type": "integer"
          },
          "total_requests": {
           "type": "integer"
          },
          "platform_health": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/dashboard",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/data-freshness": {
   "get": {
    "summary": "Data freshness monitoring",
    "description": "Returns current data freshness metrics and last update timestamps for all data sources.",
    "operationId": "getDataFreshness",
    "tags": [
     "Administration - Data Quality"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Data freshness status",
      "content": {
       "application/json": {
        "example": {
         "summary": {
          "total": 0,
          "fresh": 0,
          "aging": 0,
          "stale": 0,
          "missing": 0,
          "undeclared": 0,
          "critical_breaches": []
         },
         "sources": {
          "alternative_me_fng": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "app_store_rankings": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "artemis": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "arxiv_papers": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bcb_global": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bcb_ptax": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bis_cb_speeches": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bis_cbpol": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bis_global": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bis_reer_broad": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bis_working_papers": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          },
          "bitmex_public": {
           "source": "string",
           "label": "string",
           "sla_days": null,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": null,
           "warning": "string"
          }
         },
         "stale_sources": {
          "alternative_me_fng": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bis_cbpol": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bis_reer_broad": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bls_jolts_industry": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bls_ppi_const": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bts_border_crossings": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "bts_tsi": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "cfpb_complaints": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "cftc_cot_disagg": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "cftc_cot_supplemental": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "cftc_cot_tff": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          },
          "ecb_fx_sdw": {
           "source": "string",
           "label": "string",
           "sla_days": 0,
           "cadence": "string",
           "critical": false,
           "live_adapter": null,
           "newest_file": "string",
           "vintage": "string",
           "age_days": 0,
           "status": "string",
           "compliant": false,
           "warning": "string"
          }
         },
         "all_compliant": false
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "sources": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "source": {
              "type": "string"
             },
             "last_updated": {
              "type": "string",
              "format": "date-time"
             },
             "freshness_hours": {
              "type": "integer"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/data-freshness",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/refresh-status": {
   "get": {
    "summary": "Data refresh scheduler status",
    "description": "Returns status of the background data refresh scheduler.",
    "operationId": "getRefreshStatus",
    "tags": [
     "Administration - Data Quality"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Refresh scheduler status",
      "content": {
       "application/json": {
        "example": {
         "serving_bundle": {
          "status": "string",
          "reason": "string"
         },
         "serving_pointer": null,
         "scheduler_running": false,
         "scheduler_kind": "string",
         "how_to_run": "string",
         "wave_plan": {
          "daily": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          },
          "weekly": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          },
          "monthly": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          },
          "quarterly": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          },
          "annual": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          },
          "irregular": {
           "source_count": 0,
           "sources_preview": [
            "string"
           ]
          }
         },
         "last_updated": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "is_running": {
           "type": "boolean"
          },
          "next_refresh": {
           "type": "string",
           "format": "date-time"
          },
          "last_refresh": {
           "type": "string",
           "format": "date-time"
          },
          "sources": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/refresh-status",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/refresh-trigger": {
   "post": {
    "summary": "Trigger data refresh",
    "description": "Trigger immediate refresh of specific data sources. Body {\"job\": \"fred\"|\"bls\"|\"cremi\"} answers an honest 501 (no in-process scheduler). Body {\"job\": \"serving_bundle\"} makes THIS instance follow a server setting now (cloud pipeline, the published method note): 200 REFRESHED/UNCHANGED, 409 when the revision has no pointer, 502 when the swap failed or rolled back. Instances also poll the pointer.",
    "operationId": "postRefreshTrigger",
    "tags": [
     "Administration - Data Quality"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "sources": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Refresh triggered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "message": {
           "type": "string"
          },
          "sources": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "valid_jobs": [
          "string"
         ],
         "status_code": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_job"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/admin/refresh-trigger",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/admin/compliance": {
   "get": {
    "summary": "SOC 2 compliance dashboard",
    "description": "Returns SOC 2 compliance status and control implementation details.",
    "operationId": "getComplianceDashboard",
    "tags": [
     "Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Compliance dashboard",
      "content": {
       "application/json": {
        "example": {
         "summary": {
          "total_controls_checked": 0,
          "passed": 0,
          "failed": 0,
          "warning": 0,
          "pass_rate": "string",
          "average_confidence": "string"
         },
         "controls": {
          "A1.1": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "A1.2": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "A1.6": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "C1.1": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "C1.4": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC1.1": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC1.2": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC1.3": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC4.1": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC5.1": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC5.2": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [],
           "confidence": 0
          },
          "CC6.4": {
           "control_id": "string",
           "control_name": "string",
           "category": "string",
           "status": "string",
           "evidence": [
            "string"
           ],
           "missing": [
            "string"
           ],
           "confidence": 0
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "controls_implemented": {
           "type": "integer"
          },
          "controls_total": {
           "type": "integer"
          },
          "readiness_pct": {
           "type": "number"
          },
          "control_status": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/admin/compliance",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/explain/{prediction_id}": {
   "get": {
    "summary": "SHAP feature importance",
    "description": "Returns SHAP feature importance scores explaining a specific prediction.",
    "operationId": "getExplain",
    "tags": [
     "Explainability"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "prediction_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Feature importance",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "prediction_id": {
           "type": "string"
          },
          "features": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "importance": {
              "type": "number"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "prediction_id": "string",
         "message": "string",
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "not_found"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/explain/pred-k9-unknown",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/counterfactual/{prediction_id}": {
   "get": {
    "summary": "What-if scenarios",
    "description": "Returns counterfactual analysis for what-if scenarios.",
    "operationId": "getCounterfactual",
    "tags": [
     "Explainability"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "prediction_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_retired"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/counterfactual/pred-k9-unknown",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/audit-trail": {
   "get": {
    "summary": "Prediction audit trail",
    "description": "Query the prediction audit trail (session 2E, 2026-07-18: served from the append-only, hash-chained provenance ledger that every serving path logs to). The response includes the live hash-chain verification result. Single-tenant deployment note: tenant_id is required and echoed for the compliance record, but the ledger is platform-wide and not tenant-partitioned.\n",
    "operationId": "getAuditTrail",
    "tags": [
     "Explainability"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "tenant_id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "description": "ISO 8601 start date (inclusive)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "to",
      "in": "query",
      "description": "ISO 8601 end date (inclusive)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "engine_id",
      "in": "query",
      "description": "Matches the ledger engine field or its prefix (e.g. \"e7\" matches \"e7.default\")",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "cbsa_code",
      "in": "query",
      "description": "Matches CRE entity ids logged as \"{cbsa}:{asset}\"",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 100,
       "maximum": 10000
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Audit trail entries from the provenance ledger",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "query": {
           "type": "object"
          },
          "source": {
           "type": "string"
          },
          "tenant_note": {
           "type": "string"
          },
          "chain_valid": {
           "type": "boolean"
          },
          "chain_first_broken_index": {
           "type": "integer",
           "nullable": true
          },
          "ledger_total_predictions": {
           "type": "integer"
          },
          "results_count": {
           "type": "integer"
          },
          "returned": {
           "type": "integer"
          },
          "predictions": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "aggregated_stats": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/audit-trail",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/status": {
   "get": {
    "summary": "SOC 2 compliance status",
    "description": "Retrieve overall SOC 2 compliance status.",
    "operationId": "getSoc2Status",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "SOC 2 status",
      "content": {
       "application/json": {
        "example": {
         "compliance_score": 0,
         "status": "string",
         "controls": {
          "total": 0,
          "passing": 0,
          "failing": 0,
          "degraded": 0
         },
         "gaps": {
          "total_gaps": 0,
          "remaining_gaps": 0,
          "target_completion": "string",
          "completion_percentage": 0
         },
         "message": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/status",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/controls": {
   "get": {
    "summary": "List all SOC 2 controls",
    "description": "Retrieve all 56 SOC 2 control definitions and status.",
    "operationId": "getSoc2Controls",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "SOC 2 controls",
      "content": {
       "application/json": {
        "example": {
         "total_controls": 0,
         "matching_controls": 0,
         "controls": {
          "CC1.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC1.2": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC1.3": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC5.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC5.2": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC6.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC6.4": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC7.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC8.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "CC9.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "A1.1": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          },
          "A1.2": {
           "control_id": "string",
           "control_name": "string",
           "status": "string",
           "confidence": 0,
           "evidence": [
            "string"
           ],
           "issues": []
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "controls": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/controls",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/evidence": {
   "get": {
    "summary": "SOC 2 evidence collection status",
    "description": "Retrieve status of evidence collection for SOC 2 controls.",
    "operationId": "getSoc2Evidence",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Evidence collection status",
      "content": {
       "application/json": {
        "example": {
         "summary": {
          "total_controls": 0,
          "total_evidence_items": 0,
          "controls_with_evidence": 0,
          "controls_without_evidence": 0
         },
         "evidence": {
          "CC1.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC1.2": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC1.3": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC5.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC5.2": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC6.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC6.4": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC7.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC8.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "CC9.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "A1.1": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ],
          "A1.2": [
           {
            "control_id": "string",
            "evidence_type": "string",
            "description": "string",
            "file_path": "string",
            "collected_at": "string",
            "verified": true
           }
          ]
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/evidence",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/risks": {
   "get": {
    "summary": "SOC 2 risk register",
    "description": "Retrieve identified risks and gaps.",
    "operationId": "getSoc2Risks",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Risk register",
      "content": {
       "application/json": {
        "example": {
         "summary": {
          "total_risks": 0,
          "high_risks": 0,
          "average_risk_score": 0,
          "status_breakdown": {
           "MITIGATED": 0,
           "ACCEPTED": 0,
           "MONITORING": 0
          },
          "risks_exceeding_tolerance": 0
         },
         "risk_tolerance": 0,
         "total_risks": 0,
         "risks": [
          {
           "risk_id": "string",
           "category": "string",
           "description": "string",
           "likelihood": "string",
           "impact": "string",
           "risk_score": 0,
           "status": "string",
           "owner": "string",
           "mitigation_strategy": "string"
          }
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "risks": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/risks",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/collect-evidence": {
   "post": {
    "summary": "Trigger evidence collection",
    "description": "Trigger automated evidence collection for SOC 2.",
    "operationId": "postSoc2CollectEvidence",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Evidence collection started",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    }
   }
  },
  "/compliance/soc2/report": {
   "get": {
    "summary": "SOC 2 audit report",
    "description": "Retrieve SOC 2 audit report.",
    "operationId": "getSoc2Report",
    "tags": [
     "SOC 2 Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "SOC 2 report",
      "content": {
       "application/json": {
        "example": {
         "report_title": "string",
         "report_date": "string",
         "report_period": "string",
         "summary": {
          "total_controls": 0,
          "implemented_controls": 0,
          "effective_controls": 0,
          "compliance_score": 0
         },
         "audit_details": {
          "auditor_name": "string",
          "auditor_firm": "string",
          "audit_period_days": 0
         },
         "control_categories": [
          {
           "category_id": "string",
           "category_name": "string",
           "category_description": "string",
           "trust_services_criterion": "string",
           "total_controls": 0,
           "controls_implemented": 0,
           "controls_tested": 0,
           "completeness_score": 0,
           "controls": [
            {}
           ]
          }
         ],
         "management_assertion": {
          "assertion_date": "string",
          "period_start": "string",
          "period_end": "string",
          "assertion_statement": "string",
          "responsible_officer": "string",
          "assertion_type": "string"
         },
         "system_description": {
          "system_name": "string",
          "system_description": "string",
          "organization": "string",
          "assessment_scope": "string",
          "services": [
           "string"
          ],
          "infrastructure": [
           "string"
          ],
          "data_types": [
           "string"
          ],
          "authentication_methods": [
           "string"
          ],
          "encryption_standards": [
           "string"
          ],
          "logging_mechanisms": [
           "string"
          ]
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/report",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/classification": {
   "get": {
    "summary": "Engine risk classification",
    "description": "Retrieve AI risk classification under EU AI Act.",
    "operationId": "getEuAiActClassification",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Risk classification",
      "content": {
       "application/json": {
        "example": {
         "classification_date": "string",
         "total_engines": 0,
         "risk_summary": {
          "UNACCEPTABLE": 0,
          "HIGH": 0,
          "LIMITED": 0,
          "MINIMAL": 0
         },
         "classifications": {
          "E0": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E1": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E2": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E3": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E4": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E5": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E6": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E7": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E8": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          },
          "E9": {
           "engine_id": "string",
           "risk_level": "string",
           "annex_reference": "string",
           "rationale": "string",
           "obligations": [
            "string"
           ],
           "assessor": "string",
           "notes": "string"
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/classification",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/matrix": {
   "get": {
    "summary": "Article compliance matrix",
    "description": "Retrieve EU AI Act Article compliance matrix.",
    "operationId": "getEuAiActMatrix",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Compliance matrix",
      "content": {
       "application/json": {
        "example": {
         "total_articles": 0,
         "summary": {
          "total_articles": 0,
          "status_summary": {
           "COMPLIANT": 0,
           "PARTIAL": 0,
           "GAP": 0,
           "MINIMAL": 0,
           "NA": 0
          },
          "compliance_percentage": 0,
          "gaps": [],
          "partial_implementations": [
           "string"
          ],
          "gaps_requiring_remediation": [
           {
            "article": "string",
            "title": "string",
            "remediation_plan": "string"
           }
          ]
         },
         "items": {
          "Art. 9": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 10": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 11": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 12": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 13": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 14": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 15": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 16": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 17": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 26": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 50": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [
            "string"
           ],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          },
          "Art. 52": {
           "article_id": "string",
           "article_title": "string",
           "requirement": "string",
           "current_status": "string",
           "evidence": [],
           "remediation_plan": "string",
           "implementation_date": null,
           "responsible_team": "string",
           "notes": null
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/matrix",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/data-governance": {
   "get": {
    "summary": "Data governance records",
    "description": "Retrieve data governance and provenance records.",
    "operationId": "getEuAiActDataGovernance",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Data governance records",
      "content": {
       "application/json": {
        "example": {
         "report_type": "string",
         "generated_at": "string",
         "total_data_sources": 0,
         "quality_summary": {
          "EXCELLENT": 0,
          "GOOD": 0,
          "FAIR": 0,
          "POOR": 0
         },
         "data_sources": [
          {
           "source_name": "string",
           "source_type": "string",
           "description": "string",
           "collection_method": "string",
           "frequency": "string",
           "geographic_scope": "string",
           "record_count": 0,
           "date_range": "string",
           "quality_assessment": {
            "overall_level": "string",
            "metrics": {}
           },
           "known_biases": [
            {}
           ],
           "data_lineage": "string",
           "preprocessing_steps": [
            "string"
           ]
          }
         ],
         "known_biases_summary": {
          "TEMPORAL": [
           {
            "source": "string",
            "description": "string",
            "severity": "string"
           }
          ],
          "GEOGRAPHIC": [
           {
            "source": "string",
            "description": "string",
            "severity": "string"
           }
          ],
          "SELECTION": [
           {
            "source": "string",
            "description": "string",
            "severity": "string"
           }
          ],
          "ASSET_CLASS": [
           {
            "source": "string",
            "description": "string",
            "severity": "string"
           }
          ]
         },
         "data_retention_policy": "string",
         "next_review_date": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/data-governance",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/oversight": {
   "get": {
    "summary": "Human oversight status",
    "description": "Retrieve human oversight implementation status.",
    "operationId": "getEuAiActOversight",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Oversight status",
      "content": {
       "application/json": {
        "example": {
         "report_type": "string",
         "generated_at": "string",
         "total_review_requests": 0,
         "pending_reviews": 0,
         "by_engine": {},
         "recent_reviews": [],
         "oversight_protocols": {
          "E7": {
           "engine_id": "string",
           "description": "string",
           "review_triggers": [
            {}
           ],
           "default_reviewers": [
            "string"
           ],
           "override_allowed": true,
           "escalation_threshold": 0,
           "documentation": "string"
          },
          "E5": {
           "engine_id": "string",
           "description": "string",
           "review_triggers": [
            {}
           ],
           "default_reviewers": [
            "string"
           ],
           "override_allowed": true,
           "escalation_threshold": 0,
           "documentation": "string"
          },
          "E3": {
           "engine_id": "string",
           "description": "string",
           "review_triggers": [
            {}
           ],
           "default_reviewers": [
            "string"
           ],
           "override_allowed": true,
           "escalation_threshold": 0,
           "documentation": "string"
          },
          "ALL": {
           "engine_id": "string",
           "description": "string",
           "review_triggers": [
            {}
           ],
           "default_reviewers": [
            "string"
           ],
           "override_allowed": true,
           "escalation_threshold": 0,
           "documentation": "string"
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/oversight",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/conformity": {
   "get": {
    "summary": "Conformity assessment",
    "description": "Retrieve conformity assessment results.",
    "operationId": "getEuAiActConformity",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Conformity assessment",
      "content": {
       "application/json": {
        "example": {
         "assessment_type": "string",
         "system_identifier": "string",
         "risk_category": "string",
         "assessment_start_date": null,
         "assessment_completion_date": null,
         "assessor": null,
         "completion_percentage": 0,
         "status_summary": {
          "not_started": 0,
          "in_progress": 0,
          "complete": 0,
          "verified": 0
         },
         "items": {
          "ART-9-1": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": "string",
           "notes": null,
           "last_reviewed": null
          },
          "ART-9-2": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-9-3": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-10-1": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-10-2": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-10-3": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-10-4": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-11-1": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-11-2": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-11-3": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-12-1": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          },
          "ART-12-2": {
           "requirement_id": "string",
           "article_reference": "string",
           "requirement_description": "string",
           "status": "string",
           "evidence_count": 0,
           "evidence": [],
           "responsible_team": "string",
           "target_completion_date": "string",
           "remediation_plan": null,
           "notes": null,
           "last_reviewed": null
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/conformity",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/eu-ai-act/report": {
   "get": {
    "summary": "EU AI Act compliance report",
    "description": "Retrieve comprehensive EU AI Act compliance report.",
    "operationId": "getEuAiActReport",
    "tags": [
     "EU AI Act"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Compliance report",
      "content": {
       "application/json": {
        "example": {
         "summary": {
          "total_articles": 0,
          "status_summary": {
           "COMPLIANT": 0,
           "PARTIAL": 0,
           "GAP": 0,
           "MINIMAL": 0,
           "NA": 0
          },
          "compliance_percentage": 0,
          "gaps": [],
          "partial_implementations": [
           "string"
          ],
          "gaps_requiring_remediation": [
           {
            "article": "string",
            "title": "string",
            "remediation_plan": "string"
           }
          ]
         },
         "matrix": {
          "total_articles": 0,
          "summary": {
           "total_articles": 0,
           "status_summary": {
            "COMPLIANT": 0,
            "PARTIAL": 0,
            "GAP": 0,
            "MINIMAL": 0,
            "NA": 0
           },
           "compliance_percentage": 0,
           "gaps": [],
           "partial_implementations": [
            "string"
           ],
           "gaps_requiring_remediation": [
            {}
           ]
          },
          "items": {
           "Art. 9": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 10": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 11": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 12": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 13": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 14": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 15": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 16": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 17": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 26": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 50": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           },
           "Art. 52": {
            "article_id": "string",
            "article_title": "string",
            "requirement": "string",
            "current_status": "string",
            "evidence": [],
            "remediation_plan": "string",
            "implementation_date": null,
            "responsible_team": "string",
            "notes": null
           }
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/eu-ai-act/report",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/backtest/{engine}": {
   "get": {
    "summary": "Backtest results",
    "description": "Retrieve backtest results for a specific engine.",
    "operationId": "getValidationBacktest",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "engine",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_switched_off"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/backtest/e1",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/run": {
   "post": {
    "summary": "Trigger validation run",
    "description": "Trigger a validation run across engines.",
    "operationId": "postValidationRun",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_retired"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/validation/run",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/benchmarks": {
   "get": {
    "summary": "Academic benchmarks",
    "description": "Retrieve academic benchmark comparisons.",
    "operationId": "getValidationBenchmarks",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "engine",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_switched_off"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/benchmarks",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/significance/{engine}": {
   "get": {
    "summary": "Statistical significance tests",
    "description": "Retrieve statistical significance test results.",
    "operationId": "getValidationSignificance",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "engine",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_retired"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/significance/e1",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/stability/{engine}": {
   "get": {
    "summary": "Stability analysis",
    "description": "Retrieve stability analysis for an engine.",
    "operationId": "getValidationStability",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "engine",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_retired"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/stability/e1",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/engines/serving-status": {
   "get": {
    "summary": "Engine serving-status register (RS-06,)",
    "description": "Per-module WIRED / NOT_SERVED decision for the four built serve modules that an internal audit proved reached no API route (verification rail, crisis_ews, vol_realized, state_layer). A NOT_SERVED entry is a commitment that the capability is not advertised, with `advertising_must_be_removed` set. Read-only; writes no provenance/compliance ledger record.",
    "operationId": "getEngineServingStatus",
    "tags": [
     "Engine serving status"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "The four-module serving decision",
      "content": {
       "application/json": {
        "example": {
         "defect": "string",
         "source_of_truth": "string",
         "remediation_session": "string",
         "note": "string",
         "engines": [
          {
           "engine_id": "string",
           "module": "string",
           "serving_status": "string",
           "capability_label": "string",
           "advertising_must_be_removed": false,
           "detail_route": "string"
          }
         ],
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": true,
          "level": null,
          "as_of": null,
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/engines/serving-status",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/engines/{engine_id}": {
   "get": {
    "summary": "One engine's honest capability payload (RS-06,)",
    "description": "Serving status and honest capability label for a single engine. `vol_realized` returns its published out-of-sample EVALUATION, bound to the har_rv benchmark through the verification rail (live forecast issuance is NOT wired). `state_layer` returns state DIAGNOSTICS ONLY — `global_stress_probability` is stripped by a calibration gate that requires a positive Brier skill score against climatology on every scoring target, and currently fails. `crisis_ews` is NOT_SERVED. `verification` reports the rail's scope, which is this family only.",
    "operationId": "getEngineServingDetail",
    "tags": [
     "Engine serving status"
    ],
    "parameters": [
     {
      "name": "engine_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "verification",
        "vol_realized",
        "crisis_ews",
        "state_layer"
       ]
      }
     }
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Engine serving status and capability label",
      "content": {
       "application/json": {
        "example": {
         "engine_id": "string",
         "module": "string",
         "serving_status": "string",
         "capability_label": "string",
         "reasons": [
          {
           "code": "string",
           "detail": "string",
           "evidence": {
            "gate": "string",
            "beats_benchmark": false,
            "model_brier": 0,
            "benchmark_brier": 0,
            "skill_score": 0,
            "n": 0,
            "measured_at": "string"
           }
          }
         ],
         "advertising_must_be_removed": true,
         "advertising_surfaces": [
          "string"
         ],
         "owner_of_copy_removal": "string",
         "what_would_change_this": "string",
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": true,
          "level": null,
          "as_of": null,
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/engines/crisis_ews",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/report": {
   "get": {
    "summary": "Full validation report",
    "description": "Retrieve comprehensive validation report across all engines.",
    "operationId": "getValidationReport",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_switched_off"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/report",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/report/summary": {
   "get": {
    "summary": "Validation report summary",
    "description": "Retrieve summary statistics from validation report.",
    "operationId": "getValidationReportSummary",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_switched_off"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/report/summary",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/mfa/status": {
   "get": {
    "summary": "Two-step sign-in status (signed in)",
    "description": "(SECURITY-2). Is an authenticator enrolled, how many recovery codes are left, is it required (admin), and did THIS session pass a second factor. Session only (an API key answers 403 mfa_session_required).",
    "operationId": "getMfaStatus",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK (a signed-in session: Authorization: Bearer <session JWT>)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "description": "Captured from the served API (an API key is not a session).",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "mfa_session_required",
       "mfa_enrolment_required",
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Too many wrong codes (the sign-in throttle), or the rate limit.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "The user store could not be written; nothing was changed.",
      "x-latavis-error-codes": [
       "mfa_store_unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/auth/mfa/status",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-11-02",
     "commit": "8dc63fb"
    }
   }
  },
  "/auth/mfa/enrol/start": {
   "post": {
    "summary": "Start authenticator enrolment (signed in)",
    "description": "(SECURITY-2). A fresh TOTP secret and its otpauth:// URI (the console draws the QR code in the browser). Pending for 15 minutes; nothing is on until /auth/mfa/enrol/confirm. 409 mfa_already_enabled.",
    "operationId": "startMfaEnrolment",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK (a signed-in session: Authorization: Bearer <session JWT>)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "description": "Captured from the served API (an API key is not a session).",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "mfa_session_required",
       "mfa_enrolment_required",
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Too many wrong codes (the sign-in throttle), or the rate limit.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "The user store could not be written; nothing was changed.",
      "x-latavis-error-codes": [
       "mfa_store_unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "A wrong or expired code, or no pending enrolment.",
      "x-latavis-error-codes": [
       "mfa_invalid",
       "mfa_no_pending_enrolment",
       "bad_request"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "409": {
      "description": "Already on (start/confirm) or not on (recovery-codes/disable).",
      "x-latavis-error-codes": [
       "mfa_already_enabled",
       "mfa_not_enabled"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound (account flows 16 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/mfa/enrol/start",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-11-02",
     "commit": "8dc63fb"
    }
   }
  },
  "/auth/mfa/enrol/confirm": {
   "post": {
    "summary": "Finish enrolment with a code (signed in)",
    "description": "(SECURITY-2). Body {code}: a 6-digit code from the new authenticator (+/-30 s). Turns two-step sign-in on, returns 10 one-time recovery codes ONCE, and signs out every session of the account (reauth_required). Wrong codes count toward the sign-in throttle (400 mfa_invalid, then 429).",
    "operationId": "confirmMfaEnrolment",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "code"
        ],
        "properties": {
         "code": {
          "type": "string",
          "description": "6-digit TOTP code or a recovery code"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK (a signed-in session: Authorization: Bearer <session JWT>)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "description": "Captured from the served API (an API key is not a session).",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "mfa_session_required",
       "mfa_enrolment_required",
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Too many wrong codes (the sign-in throttle), or the rate limit.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "The user store could not be written; nothing was changed.",
      "x-latavis-error-codes": [
       "mfa_store_unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "A wrong or expired code, or no pending enrolment.",
      "x-latavis-error-codes": [
       "mfa_invalid",
       "mfa_no_pending_enrolment",
       "bad_request"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "409": {
      "description": "Already on (start/confirm) or not on (recovery-codes/disable).",
      "x-latavis-error-codes": [
       "mfa_already_enabled",
       "mfa_not_enabled"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound (account flows 16 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/mfa/enrol/confirm",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-11-02",
     "commit": "8dc63fb"
    }
   }
  },
  "/auth/mfa/recovery-codes": {
   "post": {
    "summary": "Replace the recovery codes (signed in)",
    "description": "(SECURITY-2). Body {code}: a current authenticator or recovery code. Returns 10 new recovery codes once; the old ones stop working.",
    "operationId": "regenerateMfaRecoveryCodes",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "code"
        ],
        "properties": {
         "code": {
          "type": "string",
          "description": "6-digit TOTP code or a recovery code"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK (a signed-in session: Authorization: Bearer <session JWT>)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "description": "Captured from the served API (an API key is not a session).",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "mfa_session_required",
       "mfa_enrolment_required",
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Too many wrong codes (the sign-in throttle), or the rate limit.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "The user store could not be written; nothing was changed.",
      "x-latavis-error-codes": [
       "mfa_store_unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "A wrong or expired code, or no pending enrolment.",
      "x-latavis-error-codes": [
       "mfa_invalid",
       "mfa_no_pending_enrolment",
       "bad_request"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "409": {
      "description": "Already on (start/confirm) or not on (recovery-codes/disable).",
      "x-latavis-error-codes": [
       "mfa_already_enabled",
       "mfa_not_enabled"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound (account flows 16 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/mfa/recovery-codes",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-11-02",
     "commit": "8dc63fb"
    }
   }
  },
  "/auth/mfa/disable": {
   "post": {
    "summary": "Turn two-step sign-in off (signed in)",
    "description": "(SECURITY-2). Body {code}: a current authenticator or recovery code. Signs out every session. Administrator accounts must use two-step sign-in, so an admin is asked to enrol again.",
    "operationId": "disableMfa",
    "tags": [
     "Auth"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "code"
        ],
        "properties": {
         "code": {
          "type": "string",
          "description": "6-digit TOTP code or a recovery code"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK (a signed-in session: Authorization: Bearer <session JWT>)"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "description": "Captured from the served API (an API key is not a session).",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "code": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "mfa_session_required",
       "mfa_enrolment_required",
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Too many wrong codes (the sign-in throttle), or the rate limit.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "The user store could not be written; nothing was changed.",
      "x-latavis-error-codes": [
       "mfa_store_unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "400": {
      "description": "A wrong or expired code, or no pending enrolment.",
      "x-latavis-error-codes": [
       "mfa_invalid",
       "mfa_no_pending_enrolment",
       "bad_request"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "409": {
      "description": "Already on (start/confirm) or not on (recovery-codes/disable).",
      "x-latavis-error-codes": [
       "mfa_already_enabled",
       "mfa_not_enabled"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound (account flows 16 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/mfa/disable",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-11-02",
     "commit": "8dc63fb"
    }
   }
  },
  "/auth/login": {
   "post": {
    "summary": "User login",
    "description": "Authenticate user with email and password, returns JWT tokens.",
    "operationId": "postAuthLogin",
    "tags": [
     "Authentication"
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "email",
         "password"
        ],
        "properties": {
         "email": {
          "type": "string",
          "format": "email"
         },
         "password": {
          "type": "string",
          "format": "password"
         },
         "mfa_code": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Login successful",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "access_token": {
           "type": "string"
          },
          "refresh_token": {
           "type": "string"
          },
          "token_type": {
           "type": "string"
          },
          "expires_in": {
           "type": "integer"
          },
          "user": {
           "$ref": "#/components/schemas/User"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "403": {
      "description": "the password was right and the account needs its authenticator code (mfa_required), or the code was wrong / already used (mfa_invalid; counted by the sign-in throttle). Send mfa_code.",
      "x-latavis-error-codes": [
       "mfa_required",
       "mfa_invalid"
      ],
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "mfa_required": true,
         "status_code": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/login",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/refresh": {
   "post": {
    "summary": "Refresh access token",
    "description": "Issue a refreshed session JWT (Wave 2B, 2026-07-08). The current token may be supplied as Authorization Bearer, session_token cookie, or JSON body {\"token\": ...}. Only allowed in the last 5 minutes before idle expiry, never past the 8h absolute expiry. A NEW token is minted (the old one is revoked) and also set as the session_token cookie (HttpOnly; Secure; SameSite=Strict; Path=/).\n",
    "operationId": "postAuthRefresh",
    "tags": [
     "Authentication"
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string",
          "description": "Current session JWT (alternative to header/cookie)"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Token refreshed (Set-Cookie session_token also sent)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "access_token": {
           "type": "string"
          },
          "token_type": {
           "type": "string"
          },
          "expires_at": {
           "type": "string"
          },
          "refresh_before": {
           "type": "string"
          },
          "idle_exp": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unauthenticated"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/refresh",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 401,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/logout": {
   "post": {
    "summary": "User logout",
    "description": "Revoke the current session (jti blacklisted) and clear the session_token cookie (Max-Age=0). Idempotent — returns 200 even without a valid session (Wave 2B, 2026-07-08).\n",
    "operationId": "postAuthLogout",
    "tags": [
     "Authentication"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Logout successful (cookie cleared; idempotent)",
      "content": {
       "application/json": {
        "example": {
         "message": "string",
         "session_revoked": false
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "message": {
           "type": "string"
          },
          "session_revoked": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/auth/logout",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/auth/me": {
   "get": {
    "summary": "Get current user",
    "description": "Retrieve current authenticated user information.",
    "operationId": "getAuthMe",
    "tags": [
     "Authentication"
    ],
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Current user",
      "content": {
       "application/json": {
        "example": {
         "user": {
          "id": "string",
          "email": null,
          "role": "string",
          "tenant_id": null,
          "auth_method": "string",
          "mfa_verified": false,
          "mfa_enabled": false,
          "mfa_enrolment_required": false,
          "permissions": [
           "string"
          ],
          "created_at": null,
          "last_login": null
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "user": {
           "$ref": "#/components/schemas/User"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/auth/me",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/scorecard": {
   "get": {
    "summary": "Live accuracy scorecard (agent surface)",
    "description": "Read-tier mirror of the MCP get_accuracy_scorecard tool over plain HTTP. Serves only real out-of-sample benchmark figures from the ledger; routes off the R9 fabricated-ground-truth table (SO-001). Optional ?vertical= filter.\n",
    "operationId": "getAgentScorecard",
    "tags": [
     "Agent"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Filter scorecard to one vertical"
     }
    ],
    "responses": {
     "200": {
      "description": "Live accuracy scorecard (agent surface)",
      "content": {
       "application/json": {
        "example": {
         "group_by": "string",
         "scorecard": {},
         "ledger": {
          "path": "string",
          "n_predictions": 0,
          "n_outcomes": 0,
          "chain_valid": null,
          "chain_status": "string",
          "first_broken_index": null,
          "store": "string",
          "ledger_scope": "string",
          "retention": "string",
          "retention_basis": "string",
          "chain_status_basis": "string"
         },
         "grading": {
          "available": true,
          "store": "string",
          "n_predictions": 0,
          "graded": 0,
          "pending": 0,
          "ungradeable": 0,
          "due": 0,
          "consistent": true,
          "as_of": {
           "counted_at": "string",
           "last_prediction_logged": null,
           "last_graded": null,
           "last_grader_run": null
          },
          "by_engine": {},
          "ungradeable_reasons": {},
          "statement": "string"
         },
         "settlement_registry": {
          "version": "string",
          "gradeable": [
           {
            "engine": "string",
            "signal": "string",
            "status": "string",
            "kind": "string",
            "claim": "string",
            "horizon": "string",
            "realized": "string",
            "scoring": "string",
            "benchmark": "string"
           }
          ],
          "ungradeable": [
           {
            "engine": "string",
            "signal": "string",
            "status": "string",
            "reason": "string"
           }
          ],
          "legacy_records": "string"
         },
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": false,
          "level": null,
          "as_of": null,
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "scorecard": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/scorecard",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/scorecard/public": {
   "get": {
    "summary": "Public scorecard summary (redacted, unauthenticated)",
    "description": " read-only public data source for the /accuracy page. Serves the real ledger join grouped by engine (n_scored is 0 until predictions resolve — null metrics mean \"not yet scored\"), a key-whitelisted ledger summary (no filesystem path), and the canonical validation record with per-row basis + as-of labels. No tenant, key, or usage data. Grouping is fixed to engine; query params are ignored.\n",
    "operationId": "getPublicScorecard",
    "tags": [
     "Agent"
    ],
    "security": [],
    "responses": {
     "200": {
      "description": "Public scorecard summary",
      "content": {
       "application/json": {
        "example": {
         "as_of": "string",
         "data_snapshot": {
          "status": "string",
          "reason": "string",
          "asof_by_source": null,
          "built_at": null
         },
         "as_of_basis": "string",
         "as_of_inputs": {
          "live_serving_ledger": null,
          "validation_record": "string"
         },
         "computed_at": "string",
         "live": {
          "group_by": "string",
          "scorecard": {},
          "note": "string"
         },
         "gradeability": {
          "n_unresolved": 0,
          "due": 0,
          "pending": 0,
          "ungradeable": 0,
          "reasons": {},
          "basis": "string"
         },
         "grading": {
          "available": true,
          "store": "string",
          "n_predictions": 0,
          "graded": 0,
          "pending": 0,
          "ungradeable": 0,
          "due": 0,
          "consistent": true,
          "as_of": {
           "counted_at": "string",
           "last_prediction_logged": null,
           "last_graded": null,
           "last_grader_run": null
          },
          "by_engine": {},
          "ungradeable_reasons": {},
          "statement": "string"
         },
         "settlement_registry": {
          "version": "string",
          "gradeable": [
           {
            "engine": "string",
            "signal": "string",
            "status": "string",
            "kind": "string",
            "claim": "string",
            "horizon": "string",
            "realized": "string",
            "scoring": "string",
            "benchmark": "string"
           }
          ],
          "ungradeable": [
           {
            "engine": "string",
            "signal": "string",
            "status": "string",
            "reason": "string"
           }
          ],
          "legacy_records": "string"
         },
         "ledger": {
          "n_predictions": 0,
          "n_outcomes": 0,
          "chain_valid": null,
          "chain_status": "string",
          "first_broken_index": null,
          "store": "string",
          "ledger_scope": "string",
          "retention": "string",
          "retention_basis": "string",
          "chain_status_basis": "string"
         },
         "validation_record": {
          "as_of": "string",
          "rows": [
           {
            "engine": "string",
            "metric": "string",
            "value": "string",
            "verification_level": "string",
            "as_of": "string",
            "basis": "string",
            "vertical": "string"
           }
          ]
         },
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": false,
          "level": "string",
          "as_of": "string",
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time"
          },
          "live": {
           "type": "object"
          },
          "ledger": {
           "type": "object"
          },
          "validation_record": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/scorecard/public",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/ops/freshness": {
   "get": {
    "summary": "Input freshness (as-of, cadence, last run, status of every data input)",
    "description": "COLLECTORS-CLOUD (2026-10-20). Every input the verticals read - each cloud collector, each FRED series the pipeline refreshes, and the inputs with no collector yet (listed as stale with the reason) - with the date of its latest data, its expected cadence, its last successful run and a status: fresh, late (one cadence missed), stale (more than two missed, or never run) or failed (latest run failed; served data keeps its previous as-of). Also says whether this instance serves the collector overlay. Measured from the collectors' own run records; never estimated.\n",
    "operationId": "getOpsFreshness",
    "tags": [
     "Agent"
    ],
    "parameters": [
     {
      "name": "group",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Only the inputs of one schedule group (e.g. fx-daily, pipeline-ingest-fred)."
     },
     {
      "name": "input",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Only one input (e.g. ecb_fx_sdw, fred/DGS10)."
     }
    ],
    "responses": {
     "200": {
      "description": "Freshness of every input",
      "content": {
       "application/json": {
        "example": {
         "schema": "string",
         "generated_at": "string",
         "counts": {
          "fresh": 0,
          "late": 0,
          "stale": 0,
          "failed": 0
         },
         "alerting": [
          "string"
         ],
         "fred_state_at": null,
         "inputs": [
          {
           "input": "string",
           "kind": "string",
           "table": "string",
           "title": "string",
           "url": "string",
           "group": "string",
           "licence": "string",
           "licence_unresolved": false,
           "as_of": null,
           "rows": null,
           "cadence_days": 0,
           "last_run_at": null
          }
         ],
         "overlay": {
          "state": "string",
          "reason": "string",
          "sources": null,
          "tables": null,
          "ranges": null
         },
         "table_files": {
          "holdings_13f": {
           "state": "string",
           "reason": "string",
           "master_dedup": {
            "state": "string",
            "mode": "string",
            "master_rows": 0,
            "master_filings": 0,
            "duplicate_pass_rows_hidden": 0,
            "superseded_filings_hidden": 0,
            "superseded_rows_hidden": 0,
            "rows_served": 0,
            "filings_not_in_index": null,
            "reason": "string"
           }
          },
          "call_reports": {
           "state": "string",
           "reason": "string"
          },
          "gleif_lei": {
           "state": "string",
           "reason": "string"
          },
          "ncua_call_reports": {
           "state": "string",
           "reason": "string"
          }
         },
         "serving_bundle": {
          "status": "string",
          "reason": "string"
         },
         "basis": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "schema": {
           "type": "string"
          },
          "generated_at": {
           "type": "string",
           "format": "date-time"
          },
          "counts": {
           "type": "object"
          },
          "alerting": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "overlay": {
           "type": "object"
          },
          "inputs": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/ops/freshness",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/verticals/catalog": {
   "get": {
    "summary": "Vertical + formula catalog (agent surface)",
    "description": "Read-tier mirror of the MCP get_vertical_functions tool. Lists the 14 verticals with their available =LATAVIS.* formula functions. Must be matched before the /api/v1/vertical prefix (catalog would otherwise be swallowed by the gateway).\n",
    "operationId": "getAgentCatalog",
    "tags": [
     "Agent"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Vertical + formula catalog (agent surface)",
      "content": {
       "application/json": {
        "example": {
         "verticals": [
          "string"
         ],
         "stats": {
          "total_functions": 0,
          "available_functions": 0,
          "verticals": 0,
          "by_vertical": {
           "BK": 0,
           "CM": 0,
           "CR": 0,
           "EN": 0,
           "EQ": 0,
           "FI": 0,
           "FX": 0,
           "IF": 0,
           "IL": 0,
           "LG": 0,
           "MA": 0,
           "MACRO": 0
          }
         },
         "functions": [
          {
           "signature": "string",
           "summary": "string",
           "returns": "string",
           "unit": "string",
           "source": "string",
           "available": true
          }
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "catalog": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/verticals/catalog",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/brief": {
   "get": {
    "summary": "Cited morning brief (cached per UTC day)",
    "description": "Returns the cited analyst morning brief, pre-generated in the 06:00 daily refresh and cached per UTC day. May return 202 while a brief is still generating; poll until 200.\n",
    "operationId": "getAnalystBrief",
    "tags": [
     "Analyst"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Cited morning brief (cached per UTC day)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "brief": {
           "type": "object"
          },
          "as_of": {
           "type": "string"
          },
          "cached": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "202": {
      "description": "Brief is generating; poll again"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "used_today": 0,
         "daily_budget": 0,
         "hint": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "rate_limited"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/brief",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 429,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/formula": {
   "post": {
    "summary": "Evaluate a =LATAVIS() formula (Excel add-in)",
    "description": "Evaluates a single or batch =LATAVIS.* formula for the Excel add-in (own-key model). Body carries the function name and arguments.\n",
    "operationId": "postAgentFormula",
    "tags": [
     "Agent"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "function"
        ],
        "properties": {
         "function": {
          "type": "string"
         },
         "args": {
          "type": "array"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Evaluate a =LATAVIS() formula (Excel add-in)",
      "content": {
       "application/json": {
        "example": {
         "results": [
          {
           "ok": true,
           "vertical": "string",
           "function": "string",
           "args": [
            "string"
           ],
           "value": 0,
           "unit": "string",
           "conformal_interval": null,
           "confidence": null,
           "confidence_basis": null,
           "verification_level": "string",
           "verification_label": "string",
           "confidence_cap": 0
          }
         ],
         "count": 0,
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": false,
          "level": "string",
          "as_of": "string",
          "model_id": null,
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "result": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid formula or arguments"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/formula",
      "role": "analyst",
      "body": {
       "formulas": [
        "=LATAVIS.PC.PD(\"Auctane, Inc.\")"
       ]
      },
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/chat": {
   "post": {
    "summary": "Cited analyst chat (LLM tool-use over live engines)",
    "description": "The cited analyst: an LLM that answers with citations by calling the live engine surface as tools, honoring the honesty contract (L-levels, tool transparency, no accuracy claim without OOS evidence). Clients should fall back to POST /nl/query on a 503.\n",
    "operationId": "postAnalystChat",
    "tags": [
     "Analyst"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "message"
        ],
        "properties": {
         "message": {
          "type": "string"
         },
         "context": {
          "type": "object"
         },
         "history": {
          "type": "array"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cited analyst chat (LLM tool-use over live engines)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "answer": {
           "type": "string"
          },
          "citations": {
           "type": "array"
          },
          "tools_used": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid request body",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "example": {
          "messages": [
           {
            "role": "string",
            "content": "string"
           }
          ]
         },
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/chat",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/memo": {
   "post": {
    "summary": "Cited investment memo generation",
    "description": "Generates a cited investment memo from live engine calls (verified in prod at 17 tools / 8 citations). Replaces the retired template generator at POST /reports/memo, which fabricated metrics and now returns 501.\n",
    "operationId": "postAnalystMemo",
    "tags": [
     "Analyst"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "entity_id"
        ],
        "properties": {
         "entity_id": {
          "type": "string"
         },
         "vertical": {
          "type": "string"
         },
         "sections": {
          "type": "array"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cited investment memo generation",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "memo": {
           "type": "object"
          },
          "citations": {
           "type": "array"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid request body",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "example": {
          "entity": "string",
          "vertical": "string",
          "focus": "string"
         },
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/memo",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/verticals": {
   "get": {
    "summary": "List all 14 verticals",
    "description": "Lists all 14 verticals with initialization status and a summary. One uniform contract backs every vertical; only the UI is currently bespoke.\n",
    "operationId": "listVerticals",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "List all 14 verticals",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "verticals": [
          {
           "vertical_id": "string",
           "prefix": "string",
           "status": "string",
           "sample_entities": [
            "string"
           ]
          }
         ],
         "total": 0,
         "summary": {
          "initialized": 0,
          "total": 0
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "verticals": {
           "type": "array"
          },
          "total": {
           "type": "integer"
          },
          "summary": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/verticals",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/vertical/{vertical_id}/metadata": {
   "get": {
    "summary": "Vertical engine metadata",
    "description": "Returns engine metadata (capabilities, entity type, gate status) for one vertical. 400 if the vertical is unknown.\n",
    "operationId": "getVerticalMetadata",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id, e.g. private_credit or equities"
     }
    ],
    "responses": {
     "200": {
      "description": "Vertical engine metadata",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "metadata": {
          "engine_id": "string",
          "version": "string",
          "status": "string",
          "sub_engines": [
           "string"
          ],
          "last_initialized": "string",
          "capabilities": [
           "string"
          ],
          "data_freshness": {
           "as_of_date": null,
           "as_of_basis": "string",
           "setup_day": "string"
          },
          "data_status": "string",
          "pd_lgd_model": {
           "n_borrowers": 0,
           "n_defaults": 0,
           "panel_as_of": "string",
           "panel_earliest_as_of": "string",
           "n_features": 0,
           "feature_names": [
            "string"
           ],
           "sample_sufficient": true,
           "fit_status": "string",
           "backend": "string",
           "coefficients": {
            "wavg_spread_bps": 0,
            "senior_share": 0,
            "log_exposure": 0,
            "log_n_tranches": 0
           },
           "intercept": 0,
           "feature_means": {
            "wavg_spread_bps": 0,
            "senior_share": 0,
            "log_exposure": 0,
            "log_n_tranches": 0
           }
          },
          "implementation_status": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "metadata": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown vertical"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/metadata",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/metadata",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/metadata",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/entities": {
   "get": {
    "summary": "Sample entities for a vertical",
    "description": "Returns the sample entity list (borrowers/tickers/pairs/markets/CBSAs) for a vertical, subject to free-tier truncation.\n",
    "operationId": "getVerticalEntities",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id"
     }
    ],
    "responses": {
     "200": {
      "description": "Sample entities for a vertical",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "sample_entities": [
          "string"
         ],
         "count": 0,
         "entity_basis": "string",
         "entities": [
          {
           "entity_id": "string",
           "borrower": "string",
           "bdc": "string",
           "bdc_ticker": "string",
           "bdc_tickers": [
            "string"
           ],
           "as_of": "string",
           "industry": "string",
           "n_tranches": 0,
           "total_fair_value_usd_thousands": 0,
           "on_watchlist": false,
           "pd_scoreable": true,
           "pd_refusal_reason": null
          }
         ],
         "entity_source": "string",
         "total_borrowers": 0,
         "total_tranches": 0,
         "total_bdcs": 0,
         "n_scoreable": 0,
         "n_refused": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "sample_entities": {
           "type": "array"
          },
          "count": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown vertical"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/entities",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/entities",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/entities",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/health": {
   "get": {
    "summary": "Vertical health check",
    "description": "Lightweight liveness check for a vertical engine (attempts a metadata read). 503 when the engine is degraded.\n",
    "operationId": "getVerticalHealth",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id"
     }
    ],
    "responses": {
     "200": {
      "description": "Vertical health check",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "healthy": true,
         "metadata": {
          "engine_id": "string",
          "version": "string",
          "status": "string",
          "sub_engines": [
           "string"
          ],
          "last_initialized": "string",
          "capabilities": [
           "string"
          ],
          "data_freshness": {
           "as_of_date": null,
           "as_of_basis": "string",
           "setup_day": "string"
          },
          "data_status": "string",
          "pd_lgd_model": {
           "n_borrowers": 0,
           "n_defaults": 0,
           "panel_as_of": "string",
           "panel_earliest_as_of": "string",
           "n_features": 0,
           "feature_names": [
            "string"
           ],
           "sample_sufficient": true,
           "fit_status": "string",
           "backend": "string",
           "coefficients": {
            "wavg_spread_bps": 0,
            "senior_share": 0,
            "log_exposure": 0,
            "log_n_tranches": 0
           },
           "intercept": 0,
           "feature_means": {
            "wavg_spread_bps": 0,
            "senior_share": 0,
            "log_exposure": 0,
            "log_n_tranches": 0
           }
          },
          "implementation_status": "string"
         },
         "error": null
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "healthy": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/health",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/health",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/health",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/unique": {
   "get": {
    "summary": "The vertical's unique output (DoD item 3)",
    "description": "The output a buyer cannot get from the free sources the vertical is built on: the thesis (one checkable sentence), the free alternatives checked (URL and date), every input's source and as-of, and the figures with their verification level (an em-dash with the reason where a figure cannot be shown). Optional ?entity= narrows to one bank, balancing authority, security, currency, state, port or central bank; an entity the panel does not cover answers 422 with the reason.\n",
    "operationId": "getVerticalUnique",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id"
     },
     {
      "name": "entity",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Entity the panel covers (e.g. JPM, CISO, AAPL, EUR, FL, PORT:2031, US)"
     }
    ],
    "responses": {
     "200": {
      "description": "The unique-output panel",
      "content": {
       "application/json": {
        "example": {
         "vertical": "string",
         "status": "string",
         "mode": "string",
         "entity": "string",
         "title": "string",
         "thesis": "string",
         "free_alternatives": [
          {
           "name": "string",
           "url": "string",
           "checked": "string",
           "price": "string",
           "gives": "string",
           "lacks": "string"
          }
         ],
         "kind": "string",
         "level": "string",
         "examples": [
          "string"
         ],
         "computed_at": "string",
         "sources": [
          {
           "source": "string",
           "as_of": "string",
           "licence": "string",
           "url": "string",
           "files": [
            {}
           ]
          }
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "vertical": {
           "type": "string"
          },
          "thesis": {
           "type": "string"
          },
          "free_alternatives": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "sources": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "figures": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     },
     "422": {
      "description": "Entity not covered by the panel (reason given)"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/unique",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/unique",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/unique",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/workspace": {
   "get": {
    "summary": "The dual-pane workspace: a real entity's figures beside your own position",
    "description": "WORKSPACE-2/3/4. Offered for commodities, fx, energy, banking, equities, fixed_income, macro_esg, manufacturing, logistics, private_equity, infrastructure, insurance_ils and crypto (private credit's workspace is POST /api/v1/vertical/private_credit/underwrite). `left` is the entity's served record (GET /predict/{entity}), every figure with its source, as-of, verification level and served_from; `inputs` are the caller's own numbers, labelled \"your input - not Latavis data\" and never given a level; `computed` is the stated arithmetic on both (each figure names its formula and the rows it combined; a missing input or figure is null with `missing_reason`); `forecast` is the vertical's L3 claim with its live figure for the entity (graded_live false: live grading begins once the forecast is issued and its outcome settles) - for equities, fixed income, macro & ESG and manufacturing no claim passed, so `forecast.claim` and `forecast.figure` are null, `live_grading` is null and `missing_reason` says why, and `left.unearned_forecasts` names any served forecast-kind figure no computed row uses; `honest_negatives` are the vertical's claims that did not pass; `method_parameters` declares every constant. An unknown entity answers 422 with the vertical's own reason; a bad input 400 invalid_input; no entity 400 entity_required; a vertical without a workspace 404 workspace_not_offered.\n",
    "operationId": "getVerticalWorkspace",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "commodities, fx, energy, banking, equities, fixed_income, macro_esg, manufacturing, logistics, private_equity, infrastructure, insurance_ils or crypto. WORKSPACE-4''s five cover the entity kinds named under entity; another kind of the same vertical is 422 with covered_kinds; with no passing claim (all but crypto) forecast.claim / figure / live_grading are null and missing_reason says why"
     },
     {
      "name": "entity",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "a market (CL), a currency pair (EURUSD), a balancing authority (CISO), a bank (JPM, 628), a ticker or CIK (AAPL), a Treasury tenor (UST10Y), an economy (GB) or US / NAICS:3xx / a manufacturer (F); a carrier (UNP) or port (PORT:LA); a sponsor (BX), fund (FUND:<CIK>), BDC (ARCC) or company (AAPL); an infrastructure owner (NEE) or county FIPS (12086); a state (FL), county or insurer (TRV); a crypto asset (BTC), stablecoin (USDC), futures market (CME:BTC) or protocol (PROTOCOL:LIDO)"
     },
     {
      "name": "quantity",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "commodities: your position size, in the market's unit (e.g. barrels for CL)"
     },
     {
      "name": "hedge_ratio",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "commodities, fx: the share of the position already hedged, 0-1"
     },
     {
      "name": "exposure",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "fx: your exposure, in the pair's base currency; macro_esg: your exposure in the country, in its currency"
     },
     {
      "name": "daily_load_mwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "energy: your daily electricity use, MWh"
     },
     {
      "name": "heat_rate",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "energy: your gas plant's heat rate, MMBtu/MWh"
     },
     {
      "name": "flex_mw",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "energy: your flexible capacity, MW"
     },
     {
      "name": "deposit_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "banking: your deposits at the bank, USD"
     },
     {
      "name": "ownership_categories",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "banking: your FDIC ownership categories (a whole number, at least 1)"
     },
     {
      "name": "annual_spend_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "logistics (carrier): your annual freight spend with it, USD"
     },
     {
      "name": "annual_shipments",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "logistics (carrier): your shipments a year (a whole number, at least 1)"
     },
     {
      "name": "annual_teu",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "logistics (port): your containers through it a year, TEU"
     },
     {
      "name": "import_share",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "logistics (port): the share of them that are imports, 0-1"
     },
     {
      "name": "commitment_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "private_equity (sponsor, fund): your commitment, USD"
     },
     {
      "name": "vintage_year",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "private_equity (sponsor, fund): your fund's vintage year (1946-2100)"
     },
     {
      "name": "called_share",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "private_equity (sponsor, fund): the share of your commitment called, 0-1"
     },
     {
      "name": "loan_cost_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "private_equity (BDC): your sponsor-backed loans at cost, USD"
     },
     {
      "name": "proposed_debt_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "private_equity (company): your proposed acquisition debt, USD"
     },
     {
      "name": "asset_value_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "infrastructure (owner): your asset or concession value, USD"
     },
     {
      "name": "remaining_years",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "infrastructure (owner): years left on the concession (1-99)"
     },
     {
      "name": "project_debt_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "infrastructure (owner): your project debt, USD"
     },
     {
      "name": "cash_flow_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "infrastructure (owner): your cash flow available for debt service, USD a year"
     },
     {
      "name": "building_value_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "infrastructure, insurance_ils (county): your building value there, USD"
     },
     {
      "name": "loss_share",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "insurance_ils (state): your share of the state's reported storm losses, 0-1"
     },
     {
      "name": "retention_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "insurance_ils (state): your retention before reinsurance, USD"
     },
     {
      "name": "premium_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "insurance_ils (insurer): your premium placed with it, USD a year"
     },
     {
      "name": "units_held",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "crypto (asset, stablecoin, protocol): your units held"
     },
     {
      "name": "futures_contracts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "crypto (asset, market): your open futures contracts"
     },
     {
      "name": "hashrate_ths",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "crypto (BTC): your mining fleet's hash rate, TH/s"
     },
     {
      "name": "shares_held",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "equities: your shares held"
     },
     {
      "name": "cost_per_share",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "equities: your cost per share, USD"
     },
     {
      "name": "face_usd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "fixed_income: your face amount held at the tenor, USD"
     },
     {
      "name": "rate_shock_bp",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "fixed_income: a parallel yield move to test, basis points (-1000..1000)"
     },
     {
      "name": "bond_share",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "macro_esg: the share of your exposure held in 10-year government bonds (0-1)"
     },
     {
      "name": "monthly_output",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "manufacturing: your monthly output, USD"
     },
     {
      "name": "monthly_capacity",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "manufacturing: your monthly capacity, USD"
     },
     {
      "name": "order_book",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "manufacturing: your order book, USD"
     },
     {
      "name": "hourly_wage",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "manufacturing: your average hourly wage, USD"
     },
     {
      "name": "sales_to_company",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "manufacturing (a company): your yearly sales to it, USD"
     }
    ],
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/commodities/workspace?entity=CL&quantity=10000&hedge_ratio=0.4",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "f452a01"
    },
    "responses": {
     "200": {
      "description": "The workspace (captured from the served API).",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "scope": "string",
         "entity": {
          "id": "string",
          "requested": "string",
          "name": "string",
          "kind": "string",
          "sector": "string",
          "as_of": "string",
          "verification_level": "string"
         },
         "left": {
          "title": "string",
          "figures": [
           {
            "value": 0,
            "as_of": "string",
            "unit": "string",
            "source": "string",
            "series_id": "string",
            "frequency": "string",
            "label": "string",
            "verification_level": "string",
            "level_basis": "string",
            "served_from": {},
            "key": "string",
            "origin": "string"
           }
          ],
          "not_served": [
           {
            "key": "string",
            "label": "string",
            "value": null,
            "reason": "string"
           }
          ],
          "attribution": {
           "stlouisfed_fred": "string"
          },
          "licence_disclosure": {
           "posture": "string",
           "sources": [
            {}
           ],
           "note": "string"
          }
         },
         "input_spec": [
          {
           "key": "string",
           "label": "string",
           "unit": "string",
           "min": 0,
           "help": "string"
          }
         ],
         "inputs": {
          "quantity": {
           "key": "string",
           "label": "string",
           "value": 0,
           "unit": "string",
           "source": "string",
           "kind": "string",
           "origin": "string",
           "label_origin": "string",
           "as_of": null,
           "verification_level": null,
           "served_from": {
            "path": "string",
            "source": "string",
            "basis": "string"
           }
          },
          "hedge_ratio": {
           "key": "string",
           "label": "string",
           "value": 0,
           "unit": "string",
           "source": "string",
           "kind": "string",
           "origin": "string",
           "label_origin": "string",
           "as_of": null,
           "verification_level": null,
           "served_from": {
            "path": "string",
            "source": "string",
            "basis": "string"
           }
          }
         },
         "computed": [
          {
           "key": "string",
           "label": "string",
           "unit": "string",
           "kind": "string",
           "origin": "string",
           "method": "string",
           "inputs": [
            {}
           ],
           "verification_level": null,
           "level_basis": "string",
           "sources": [
            "string"
           ],
           "customer_only": false,
           "as_of": "string"
          }
         ],
         "forecast": {
          "claim": {
           "key": "string",
           "engine": "string",
           "claim_id": "string",
           "title": "string",
           "claim": "string",
           "horizon": "string",
           "settlement": "string",
           "baseline": "string",
           "verdict": "string",
           "status": "string",
           "result": "string",
           "verification_level": "string"
          },
          "figure": {
           "entity": "string",
           "figure": "string",
           "value": 0,
           "unit": "string",
           "target_month": "string",
           "as_of": "string",
           "source": "string",
           "verification_level": "string",
           "attribution": "string",
           "forecast_status": "string",
           "baselines": {
            "last12_1sd_pct": 0,
            "expanding_1sd_pct": 0
           },
           "key": "string"
          },
          "missing_reason": null,
          "live_grading": "string",
          "graded_live": false
         },
         "honest_negatives": [
          {
           "key": "string",
           "engine": "string",
           "claim_id": "string",
           "title": "string",
           "claim": "string",
           "horizon": "string",
           "settlement": "string",
           "baseline": "string",
           "verdict": "string",
           "status": "string",
           "result": "string",
           "verification_level": "string"
          }
         ],
         "method_parameters": [
          {
           "role": "string",
           "value": 0,
           "unit": "string",
           "source": "string",
           "kind": "string",
           "ref": "string",
           "as_of": null,
           "key": "string",
           "label": "string",
           "note": "string",
           "served_from": {
            "path": "string",
            "source": "string",
            "basis": "string"
           }
          }
         ],
         "honesty": {
          "customer_inputs": "string",
          "computed": "string",
          "missing": "string",
          "verdict": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical",
       "workspace_not_offered"
      ]
     },
     "400": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "vertical_id": "string",
         "error": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "entity_required",
       "invalid_input"
      ]
     },
     "422": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "vertical_id": "string",
         "code": "string",
         "error": "string",
         "entity": "string",
         "refusal": {
          "resolved": false,
          "requested_entity": "string",
          "reason_code": "string",
          "reason": "string",
          "near_matches": [],
          "known_markets": [
           "string"
          ],
          "aliases": {
           "W": "string"
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_currency_pair",
       "unknown_market",
       "ticker_not_found",
       "unknown_entity",
       "not_a_treasury_tenor",
       "not_a_country",
       "not_an_sec_filer",
       "not_a_carrier_or_port",
       "not_a_sponsor_fund_lender_or_company",
       "unknown_infrastructure_entity",
       "not_an_owner_or_county",
       "unknown_insurance_entity",
       "not_an_insurer_state_or_county",
       "not_a_crypto_entity",
       "not_a_crypto_asset_or_market"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/workspace?entity=CL&quantity=10000&hedge_ratio=0.4",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/workspace?entity=CL&quantity=10000&hedge_ratio=0.4",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "workspace_not_offered",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/private_credit/workspace?entity=Pluralsight%2C%20LLC",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "workspace_not_offered",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "entity_required",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/commodities/workspace",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 400,
      "code": "entity_required",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "invalid_input",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/commodities/workspace?entity=CL&hedge_ratio=2",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 400,
      "code": "invalid_input",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "unknown_market",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/commodities/workspace?entity=ZZFAKE",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 422,
      "code": "unknown_market",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     },
     {
      "name": "fx_not_a_pair",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/fx/workspace?entity=ZZZ_NOT_A_CCY",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 422,
      "code": "not_a_currency_pair",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "f452a01"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/predict/{entity_id}": {
   "get": {
    "summary": "Single-entity prediction",
    "description": "Returns a single-entity prediction payload for a vertical. One payload drives the workspace tabs (the PC pattern). Supports ?as_of_date= and engine-specific query params. The 0.30 confidence cap applies until a vertical passes the validation gauntlet.\n",
    "operationId": "getVerticalPredict",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id"
     },
     {
      "name": "entity_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Entity id, e.g. AAPL"
     },
     {
      "name": "as_of_date",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "ISO date for the prediction as-of"
     }
    ],
    "responses": {
     "200": {
      "description": "Single-entity prediction",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "entity_id": "string",
         "scope": "string",
         "prediction": {
          "engine": "string",
          "version": "string",
          "deal_name": "string",
          "borrower": "string",
          "facility_size_mm": 0,
          "spread_bps": 0,
          "leverage": null,
          "dscr": null,
          "ltv": null,
          "impairment_score": 0,
          "lgd": 0,
          "impairment_weighted_loss_mm": 0
         },
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": false,
          "level": "string",
          "as_of": "string",
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "entity_id": {
           "type": "string"
          },
          "scope": {
           "type": "string"
          },
          "prediction": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown vertical or entity"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     },
     "422": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "vertical_id": "string",
         "entity_id": "string",
         "scope": "string",
         "refusal": {
          "resolved": false,
          "requested_entity": "string",
          "reason_code": "string",
          "reason": "string",
          "near_matches": [
           "string"
          ]
         },
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_currency_pair",
       "not_in_panel",
       "ticker_not_found"
      ]
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/predict/Auctane%2C%20Inc.",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/predict/Auctane%2C%20Inc.",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/predict/Auctane%2C%20Inc.",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "pc_not_a_borrower",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/private_credit/predict/Not%20A%20Borrower%20LLC",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 422,
      "code": "not_in_panel",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "equities_no_such_ticker",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/equities/predict/NO_SUCH_TICKER_ZZZ",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 422,
      "code": "ticker_not_found",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "fx_not_a_pair",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/fx/predict/ZZZ_NOT_A_CCY",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 422,
      "code": "not_a_currency_pair",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/vertical/{vertical_id}/predict/national": {
   "get": {
    "summary": "National / market-summary prediction",
    "description": "Returns the national/market-level aggregation for a vertical (used today by the PC portfolio rollup via HHI / weighted-PD). Supports engine-specific query params.\n",
    "operationId": "getVerticalNational",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id"
     }
    ],
    "responses": {
     "200": {
      "description": "National / market-summary prediction",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "vertical_id": "string",
         "scope": "string",
         "prediction": {
          "engine": "string",
          "version": "string",
          "data_status": "string",
          "data_basis_note": "string",
          "portfolio_name": "string",
          "as_of_date": "string",
          "total_entities_analyzed": 0,
          "total_par_mm": 0,
          "total_fair_value_mm": 0,
          "total_cost_mm": 0,
          "weighted_avg_leverage": null,
          "weighted_avg_dscr": null
         },
         "_verification": {
          "status": "string",
          "verified": false,
          "label": "string",
          "rail": "string",
          "on_rail_route": false,
          "level": null,
          "as_of": "string",
          "model_id": "string",
          "model_version": null,
          "benchmark": null,
          "evidence_state": "string",
          "evidence_basis": "string"
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "scope": {
           "type": "string"
          },
          "prediction": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown vertical"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "vertical_id": "string",
         "known_verticals": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "unknown_vertical"
      ]
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/vertical/private_credit/predict/national",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/not_a_vertical/predict/national",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": true,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "GET",
       "path": "/api/v1/vertical/cre/predict/national",
       "role": "analyst",
       "body": null,
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/analytics/fi/{calculator}": {
   "post": {
    "summary": "Fixed-income risk on your own positions, and the fixed-income calculators",
    "description": "VERT-FI / (2026-11-03). Priced off the day's served US Treasury curve (observed par at every published tenor, the pre-registered PCHIP interpolant between, zeros only inside the observed span). portfolio: positions [{id, cusip, face, coupon_pct, maturity_years, price or yield_pct}] -> price, yield, z-spread, modified duration, convexity, DV01 and key-rate DV01s per position, book totals, scenario P&L (parallel +/-100, +25, bear steepener, bull flattener; full revaluation) and 1-day 99% historical VaR / 97.5% ES. Calculators: conversion-factor (CME rule), frn (discount margin), municipal (tax-equivalent yield, de minimis), horizon (carry and roll per served tenor), asset-swap (vs the Treasury zero curve), swaption (Black and Bachelier; the caller supplies the vol), breakeven-curve (TIPS-implied term structure and 5y5y), cusip (VERT-FI-2 US Treasury terms from Treasury's auction record, {cusip} or {cusips: [...]}; a portfolio position may give only a Treasury cusip, face and price or yield_pct, and takes coupon and maturity from that record). A missing market input or a position beyond the curve's longest tenor answers 422 with the reason; nothing is defaulted. Verification level L1 (pricing arithmetic, not a forecast).",
    "operationId": "postFixedIncomeAnalytics",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "calculator",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "portfolio",
        "conversion-factor",
        "frn",
        "municipal",
        "horizon",
        "asset-swap",
        "swaption",
        "breakeven-curve",
        "cusip"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "description": "The calculator's inputs (see the description); portfolio takes a positions list."
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The calculator's result with the curve's source, date and method",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "calculator": {
           "type": "string"
          },
          "result": {
           "type": "object"
          },
          "market": {
           "type": "object"
          },
          "verification_level": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A missing or malformed input"
     },
     "404": {
      "description": "Unknown calculator"
     },
     "422": {
      "description": "The market cannot answer (curve unavailable, position beyond the observed span, unreachable price)"
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    }
   }
  },
  "/api/v1/vertical/{vertical_id}/underwrite": {
   "post": {
    "summary": "Underwrite a customer-entered deal",
    "description": "(UNDERWRITE-ON, 2026-10-31). Screens a private-credit deal: either a REAL borrower from the SEC EDGAR BDC panel (`borrower`, its filed name; resolved exactly as GET /api/v1/vertical/private_credit/predict/{entity_id}, including a filer's own printed spelling of a merged borrower,) or a deal the caller enters. For a panel borrower the `panel` block carries its filed status, non-accrual count, lenders, exposure at par, cost, lender fair value and mark, markdown, spread, LGD on par and disclosed-impairment score, each with the source, as-of and verification level of the served record; a figure no served block covers is null with a reason. Every input the screen used is listed in `inputs_used` with its origin: customer_input (never badged as Latavis data) or panel (with its passport). The gate is decided by the caller's own leverage, interest coverage, LTV and fixed-charge coverage; the impairment score is shown beside it, never in it; a test whose input is missing reads not_tested and a screen without both core tests reads INSUFFICIENT_METHOD. An unknown borrower, or one of the fictional sample-deal ids, answers 422 with the resolver's reason code. Only private_credit has this route; another vertical answers 404 underwrite_not_offered / unknown_vertical. Confidence is capped at 0.50 (private_credit is fitted, not out-of-sample validated).",
    "operationId": "postVerticalUnderwrite",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "vertical_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Vertical id (only private_credit is supported)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "description": "facility_size_mm, wavg_spread_bps, ebitda_mm and total_debt_mm are required for a customer-entered deal; with `borrower` nothing is required.",
        "properties": {
         "borrower": {
          "type": "string",
          "description": "A real borrower by its filed name (SEC EDGAR BDC panel). Omit for your own deal."
         },
         "borrower_label": {
          "type": "string"
         },
         "facility_type": {
          "type": "string"
         },
         "facility_size_mm": {
          "type": "number"
         },
         "total_principal_mm": {
          "type": "number"
         },
         "wavg_spread_bps": {
          "type": "number"
         },
         "ebitda_mm": {
          "type": "number"
         },
         "total_debt_mm": {
          "type": "number"
         },
         "interest_expense_mm": {
          "type": "number"
         },
         "collateral_value_mm": {
          "type": "number"
         },
         "liquidity_mm": {
          "type": "number"
         },
         "fixed_charges_mm": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Scored deal with gate, covenants, and honesty envelope",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "vertical_id": {
           "type": "string"
          },
          "deal_kind": {
           "type": "string",
           "enum": [
            "panel_borrower",
            "customer_entered"
           ]
          },
          "borrower": {
           "type": "string",
           "nullable": true
          },
          "panel": {
           "type": "object",
           "nullable": true
          },
          "inputs_used": {
           "type": "object"
          },
          "derived": {
           "type": "object"
          },
          "pd_lgd": {
           "type": "object"
          },
          "covenants": {
           "type": "array"
          },
          "gate": {
           "type": "object"
          },
          "honesty": {
           "type": "object"
          }
         }
        },
        "example": {
         "status": "string",
         "vertical_id": "string",
         "deal_kind": "string",
         "borrower": "string",
         "panel": {
          "borrower": "string",
          "resolution": {
           "resolved": true,
           "requested_entity": "string",
           "analyzed_borrower": "string",
           "substituted": false,
           "match_type": "string",
           "n_tranches": 0,
           "bdc_tickers": [
            "string"
           ],
           "reason": "string"
          },
          "as_of": "string",
          "as_of_basis": "string",
          "filed": "string",
          "data_status": "string",
          "data_vintages": {
           "sec_edgar_bdc_soi": {
            "as_of": "string",
            "source": "string",
            "age_days": 0,
            "sla_days": null,
            "verdict": "string",
            "basis": "string"
           }
          },
          "figures": [
           {
            "key": "string",
            "label": "string",
            "unit": "string",
            "origin": "string",
            "value": "string",
            "source": "string",
            "source_name": "string",
            "as_of": "string",
            "level": "string",
            "kind": "string",
            "method": "string",
            "table": "string"
           }
          ],
          "not_disclosed": {
           "leverage": "string",
           "dscr": "string",
           "ltv": "string",
           "covenant_headroom_pct": "string"
          },
          "basis": "string"
         },
         "inputs_used": {
          "ebitda_mm": {
           "value": 0,
           "origin": "string",
           "label": "string"
          },
          "total_debt_mm": {
           "value": 0,
           "origin": "string",
           "label": "string"
          },
          "interest_expense_mm": {
           "value": 0,
           "origin": "string",
           "label": "string"
          },
          "collateral_value_mm": {
           "value": 0,
           "origin": "string",
           "label": "string"
          },
          "facility_size_mm": {
           "value": 0,
           "origin": "string",
           "source": "string",
           "as_of": "string",
           "level": "string",
           "label": "string"
          },
          "wavg_spread_bps": {
           "value": 0,
           "origin": "string",
           "source": "string",
           "as_of": "string",
           "level": "string",
           "label": "string"
          }
         },
         "borrower_label": null,
         "facility_type": "string",
         "derived": {
          "leverage": 0,
          "interest_coverage": 0,
          "ltv": 0,
          "fixed_charge_coverage": null,
          "impairment_weighted_loss_mm": 0,
          "impairment_weighted_loss_label": "string",
          "expected_loss_mm": 0,
          "deprecated_fields": {
           "expected_loss_mm": "string"
          },
          "basis": "string"
         },
         "pd_lgd": {
          "available": true,
          "origin": "string",
          "impairment_score": 0,
          "score_label": "string",
          "score_basis": "string",
          "score_horizon": null,
          "pd_ci_low": 0,
          "pd_ci_high": 0,
          "ci_basis": "string",
          "score_source": "string",
          "score_as_of": "string",
          "score_level": "string"
         },
         "covenants": [
          {
           "name": "string",
           "actual": 0,
           "threshold": 0,
           "kind": "string",
           "unit": "string",
           "headroom_x": 0,
           "cushion_pct": 0,
           "is_breached": false,
           "status": "string",
           "status_basis": "string",
           "ebitda_decline_to_breach_pct": 0,
           "ebitda_decline_to_breach_mm": 0
          }
         ],
         "gate": {
          "verdict": "string",
          "headline": "string",
          "tests": [
           {
            "name": "string",
            "actual": 0,
            "threshold": 0,
            "kind": "string",
            "result": "string",
            "near_limit": false,
            "margin_pct": 0,
            "format": "string",
            "note": "string"
           }
          ],
          "n_passed": 0,
          "n_failed": 0,
          "n_not_tested": 0,
          "n_not_gated": 0,
          "core_tests": [
           "string"
          ],
          "core_tests_missing": [],
          "criteria_source": "string",
          "advance_allowed": true,
          "thresholds": {
           "values": {
            "max_leverage": 0,
            "min_coverage": 0,
            "max_pd": 0,
            "max_ltv": 0,
            "min_fccr": 0
           },
           "source": {
            "max_leverage": "string",
            "min_coverage": "string",
            "max_pd": "string",
            "max_ltv": "string",
            "min_fccr": "string"
           },
           "spec_defaults": {
            "max_leverage": 0,
            "min_coverage": 0,
            "max_pd": 0,
            "max_ltv": 0,
            "min_fccr": 0
           },
           "is_default": true,
           "basis": "string"
          }
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      }
     },
     "400": {
      "description": "Invalid input (a customer-entered deal missing a required input, a negative or zero divisor, an unknown facility type).",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "details": [
          "string"
         ],
         "expected_inputs": {
          "borrower": "string",
          "borrower_label": "string",
          "facility_type": "string",
          "facility_size_mm": "string",
          "wavg_spread_bps": "string",
          "ebitda_mm": "string",
          "total_debt_mm": "string",
          "interest_expense_mm": "string",
          "collateral_value_mm": "string",
          "liquidity_mm": "string",
          "fixed_charges_mm": "string",
          "total_principal_mm": "string"
         },
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "422": {
      "description": "The borrower is not in the panel, is a fictional sample-deal id, or is a filer spelling printed under two borrowers. The resolver's refusal is carried verbatim.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "code": "string",
         "reason_code": "string",
         "error": "string",
         "requested_borrower": "string",
         "near_matches": [],
         "refusal": {
          "resolved": false,
          "requested_entity": "string",
          "reason_code": "string",
          "reason": "string",
          "near_matches": []
         },
         "hint": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "not_in_panel",
       "ambiguous_spelling",
       "empty_entity_id"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API (an error answer).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        },
        "example": {
         "status": "string",
         "code": "string",
         "error": "string",
         "available_for": [
          "string"
         ],
         "reason": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of."
       }
      },
      "x-latavis-error-codes": [
       "not_a_latavis_offering",
       "underwrite_not_offered",
       "unknown_vertical"
      ]
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/vertical/private_credit/underwrite",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    },
    "x-latavis-error-captures": [
     {
      "name": "unknown_vertical",
      "request": {
       "method": "POST",
       "path": "/api/v1/vertical/not_a_vertical/underwrite",
       "role": "analyst",
       "body": {},
       "skip_live": false
      },
      "status": 404,
      "code": "unknown_vertical",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "cre",
      "request": {
       "method": "POST",
       "path": "/api/v1/vertical/cre/underwrite",
       "role": "analyst",
       "body": {},
       "skip_live": false
      },
      "status": 404,
      "code": "not_a_latavis_offering",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     },
     {
      "name": "underwrite_not_offered",
      "request": {
       "method": "POST",
       "path": "/api/v1/vertical/fx/underwrite",
       "role": "analyst",
       "body": {},
       "skip_live": false
      },
      "status": 404,
      "code": "underwrite_not_offered",
      "estate": false,
      "captured": "2026-10-31",
      "commit": "0a21c35"
     }
    ]
   }
  },
  "/api/v1/deals": {
   "get": {
    "summary": "List deals in your tenant",
    "description": "Returns the caller's tenant's active deals, most recently updated first. Scope is the tenant, not the user, so a colleague's deal is visible; another tenant's is not. List rows carry a verdict chip rather than the full scoring envelope.\n",
    "operationId": "listDeals",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Deals in the caller's tenant",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "count": {
           "type": "integer"
          },
          "deals": {
           "type": "array"
          },
          "scope": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Credential carries no tenant; deals are not filed under a shared default",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/deals",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Create a deal",
    "operationId": "createDeal",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "label": {
          "type": "string"
         },
         "vertical": {
          "type": "string"
         },
         "inputs": {
          "type": "object",
          "description": "Flat string map of deal inputs (the client's DealInputs)"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Created",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "deal": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid inputs, or the tenant deal limit is reached"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Credential carries no tenant",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/deals",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/deals/{deal_id}": {
   "get": {
    "summary": "Fetch one deal",
    "description": "Returns 404 for a deal in another tenant, identically to a deal that never existed. A 403 would confirm the id is real and turn the id space into an existence oracle.\n",
    "operationId": "getDeal",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The deal, including its last scoring envelope",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "deal": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/deals/987654",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "patch": {
    "summary": "Update a deal",
    "description": "Partial update of inputs, label, or stage. Changing inputs CLEARS the stored scoring result — a verdict shown beside inputs that have since changed is a stale verdict, and the server will not keep one.\n",
    "operationId": "updateDeal",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "inputs": {
          "type": "object"
         },
         "label": {
          "type": "string"
         },
         "stage": {
          "type": "integer"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Updated deal"
     },
     "400": {
      "description": "Nothing to update, or invalid field"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "PATCH",
      "path": "/api/v1/deals/987654",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "delete": {
    "summary": "Delete a deal (soft)",
    "operationId": "deleteDeal",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Deleted"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "DELETE",
      "path": "/api/v1/deals/987654",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/deals/{deal_id}/score": {
   "post": {
    "summary": "Score a stored deal and persist the result",
    "description": "Scores the STORED inputs, not a body payload, so the persisted envelope always corresponds to the persisted inputs. Pass {\"advance\": true} to stamp the next stage; the server re-checks gate.advance_allowed rather than trusting the client, because a client that could advance itself past a DECLINE would make the gate decorative.\n",
    "operationId": "scoreDeal",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "advance": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Scoring envelope plus the updated deal",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "deal": {
           "type": "object"
          },
          "result": {
           "type": "object"
          },
          "advanced": {
           "type": "boolean"
          },
          "advance_allowed": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Stored inputs are not scorable"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/deals/987654/score",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/deals/{deal_id}/override": {
   "get": {
    "summary": "Every override recorded against this deal",
    "description": "Append-only. Overrides cannot be edited or deleted — an override record that can be revised afterwards is worse than none, because it still reads as authoritative.\n",
    "operationId": "listDealOverrides",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The override history"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/deals/987654/override",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Advance past a gate that did not pass, on the record",
    "description": "Records who overrode, when, at which stage, which verdict was overruled and which tests were failing at that moment, then advances the stage in the same transaction. A rationale of at least 40 characters is required. The overridden verdict and the failing tests are read from the SERVER's stored result, never from the request — a client that could name its own overridden verdict could record an override of a DECLINE as an override of a CONDITIONAL.\n",
    "operationId": "createDealOverride",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "rationale"
        ],
        "properties": {
         "rationale": {
          "type": "string",
          "minLength": 40
         },
         "stage": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "The recorded override and the advanced deal"
     },
     "400": {
      "description": "Rationale too short, or the gate does not read DECLINE/CONDITIONAL"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant"
     },
     "403": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "error": "string",
         "detail": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/deals/987654/override",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/underwrite/thresholds": {
   "get": {
    "summary": "The screening thresholds in force, and where they came from",
    "description": "Returns the leverage / coverage / PD / LTV / FCCR box used by the stage-1 gate, with a PER-KEY source of `default` or `tenant`. A tenant that overrides only leverage is running four spec numbers and one of its own, and a single \"customised\" flag would hide that. A threshold you cannot trace is indistinguishable from one we invented.\n",
    "operationId": "getUnderwriteThresholds",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Values, per-key provenance, and the spec defaults for comparison",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "thresholds": {
          "values": {
           "max_leverage": 0,
           "min_coverage": 0,
           "max_pd": 0,
           "max_ltv": 0,
           "min_fccr": 0
          },
          "source": {
           "max_leverage": "string",
           "min_coverage": "string",
           "max_pd": "string",
           "max_ltv": "string",
           "min_fccr": "string"
          },
          "spec_defaults": {
           "max_leverage": 0,
           "min_coverage": 0,
           "max_pd": 0,
           "max_ltv": 0,
           "min_fccr": 0
          },
          "is_default": true,
          "basis": "string"
         },
         "editable": false
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "thresholds": {
           "type": "object"
          },
          "editable": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/underwrite/thresholds",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "put": {
    "summary": "Set this tenant's screening box (admin)",
    "description": "Requires the tenant-management permission: moving the leverage ceiling changes what the firm will lend against, which is not an analyst's decision to make alone. Refuses with 404 when the tenant is not provisioned rather than creating a tenant record as a side effect of saving a threshold.\n",
    "operationId": "putUnderwriteThresholds",
    "tags": [
     "Vertical API"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "thresholds": {
          "type": "object",
          "properties": {
           "max_leverage": {
            "type": "number"
           },
           "min_coverage": {
            "type": "number"
           },
           "max_pd": {
            "type": "number"
           },
           "max_ltv": {
            "type": "number"
           },
           "min_fccr": {
            "type": "number"
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The thresholds now in force"
     },
     "400": {
      "description": "Unknown or out-of-range threshold"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "Credential carries no tenant",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "forbidden"
      ]
     },
     "404": {
      "description": "Tenant not provisioned; the spec defaults remain in force"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "manage_tenants"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "PUT",
      "path": "/api/v1/underwrite/thresholds",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 403,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/deals/{deal_id}/stage/{stage}": {
   "get": {
    "summary": "The last computed result for a workflow stage",
    "operationId": "getDealStage",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "stage",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 5
      },
      "description": "1 Screen, 2 Underwrite, 3 Credit analysis, 4 IC memo, 5 Monitor"
     }
    ],
    "responses": {
     "200": {
      "description": "Stage inputs, last result, and when it was computed"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant, or no such stage",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "not_found"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "read_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/deals/987654/stage/screen",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   },
   "post": {
    "summary": "Compute a workflow stage and persist it",
    "description": "Stages 2-5 of WORKFLOW_07. Stage 2 builds normalized EBITDA, a 5-7 year projection, a debt schedule and lender IRR under base/downside/distress. Stage 3 tests the covenant package and the IC criteria. Stage 4 drafts the IC memo from the deal's own figures — computed facts are cited to their source field and judgement sections are returned as prompts, never as generated prose. Stage 5 compares reported actuals against the stage-2 base projection and re-scores the PD for the workout trigger. Stage 1 is POST /api/v1/deals/{deal_id}/score, not this endpoint. Where Latavis cannot compute something the spec names — there is no 1-10 credit score, a committee vote is not a computation, a breach probability needs a volatility you supply — the stage returns not_tested with a reason instead of a number.\n",
    "operationId": "computeDealStage",
    "tags": [
     "Deals"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "deal_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "stage",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 2,
       "maximum": 5
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "inputs": {
          "type": "object",
          "description": "Stage-specific assumptions, add-backs, covenant levels, vote, or actuals"
         },
         "advance": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The computed stage, its gate, and the updated deal",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "stage": {
           "type": "integer"
          },
          "result": {
           "type": "object"
          },
          "deal": {
           "type": "object"
          },
          "advanced": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Stage not computable from what is stored (the reason says what is missing)"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "No such deal in your tenant",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "status_code": 0,
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "not_found"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/deals/987654/stage/screen",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/leads": {
   "post": {
    "summary": "Submit a \"Request access\" lead (public)",
    "description": "M5 (2026-10-12): the public marketing site's access-request form. No authentication. Stored in the `leads` table; the client IP is never stored (only a salted SHA-256 ip_hash). A non-empty honeypot field `website` is answered 200 {\"ok\": true} and nothing is stored. Rate limits: 5 per IP per 10 minutes and 50 per hour overall, enforced both in-process (per instance) and against the database (across instances). Only POST is served on this path.\n",
    "operationId": "createLead",
    "tags": [
     "Leads"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "email"
        ],
        "properties": {
         "email": {
          "type": "string",
          "format": "email",
          "maxLength": 254
         },
         "name": {
          "type": "string",
          "maxLength": 120
         },
         "firm": {
          "type": "string",
          "maxLength": 200
         },
         "segment": {
          "type": "string",
          "enum": [
           "direct_lender",
           "bdc",
           "private_credit_fund",
           "bank",
           "insurer",
           "other"
          ]
         },
         "message": {
          "type": "string",
          "maxLength": 2000
         },
         "source_page": {
          "type": "string",
          "maxLength": 200,
          "description": "Site path the form was on; must start with \"/\""
         },
         "website": {
          "type": "string",
          "description": "Honeypot - must be left empty (hidden from humans)"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Lead stored",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "200": {
      "description": "Honeypot filled - acknowledged, nothing stored",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid lead (code invalid_lead; error says which field)",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "invalid_lead"
      ]
     },
     "429": {
      "description": "Rate limited (code rate_limited); Retry-After header is also set",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "error": {
           "type": "string"
          },
          "code": {
           "type": "string"
          },
          "retry_after_seconds": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "invalid_lead",
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/leads",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/admin/leads": {
   "get": {
    "summary": "List public-site leads (admin only)",
    "description": "Newest first. ip_hash is never returned. Requires the admin role (ADMIN_OPS).\n",
    "operationId": "listLeads",
    "tags": [
     "Leads"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200,
       "default": 50
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Leads, newest first",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "total": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "offset": {
           "type": "integer"
          },
          "leads": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "created_at": {
              "type": "string",
              "format": "date-time"
             },
             "email": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "firm": {
              "type": "string"
             },
             "segment": {
              "type": "string"
             },
             "message": {
              "type": "string"
             },
             "source_page": {
              "type": "string"
             },
             "user_agent": {
              "type": "string"
             },
             "status": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "limit/offset not integers or out of range (code invalid_query)"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Lead store unavailable (code lead_store_unavailable)",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "lead_store_unavailable"
      ]
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/admin/leads",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/conditioning": {
   "get": {
    "summary": "Cross-vertical conditioning (S4)",
    "description": "Read-only hook into engines.cross_vertical: returns the conditioning signal one vertical exerts on another. Additive and fail-safe.\n",
    "operationId": "getCrossConditioning",
    "tags": [
     "Cross-Vertical"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Cross-vertical conditioning (S4)",
      "content": {
       "application/json": {
        "example": {
         "scenario": "string",
         "as_of_date": "string",
         "as_of_basis": "string",
         "as_of_inputs": {
          "fred GDPC1": "string",
          "fred CPIAUCSL": "string",
          "fred FEDFUNDS": "string",
          "fred UNRATE": "string",
          "fred T10Y2Y": "string",
          "fx_context EURUSD": "string",
          "fx_context GBPUSD": "string",
          "fx_context USDJPY": "string"
         },
         "macro_interface": "string",
         "conditioning": {
          "scenario": "string",
          "ma_scenario": "string",
          "probability": 0,
          "horizon": "string",
          "gdp_growth_pct": 0,
          "inflation_pct": 0,
          "unemployment_pct": 0,
          "policy_rate_pct": 0,
          "terminal_policy_rate_pct": 0,
          "yield_10y_pct": 0,
          "credit_spread_bps": 0,
          "rate_path": {
           "Q1": 0,
           "Q2": 0,
           "Q3": 0,
           "Q4": 0,
           "block_provenance": {
            "source": "string",
            "as_of": null,
            "level": null,
            "kind": "string",
            "covers": "string",
            "ref": "string",
            "method": "string"
           }
          }
         },
         "all_scenarios": {
          "base": {
           "scenario": "string",
           "ma_scenario": "string",
           "probability": 0,
           "horizon": "string",
           "gdp_growth_pct": 0,
           "inflation_pct": 0,
           "unemployment_pct": 0,
           "policy_rate_pct": 0,
           "terminal_policy_rate_pct": 0,
           "yield_10y_pct": 0,
           "credit_spread_bps": 0,
           "rate_path": {
            "Q1": 0,
            "Q2": 0,
            "Q3": 0,
            "Q4": 0,
            "block_provenance": {}
           }
          },
          "bull": {
           "scenario": "string",
           "ma_scenario": "string",
           "probability": 0,
           "horizon": "string",
           "gdp_growth_pct": 0,
           "inflation_pct": 0,
           "unemployment_pct": 0,
           "policy_rate_pct": 0,
           "terminal_policy_rate_pct": 0,
           "yield_10y_pct": 0,
           "credit_spread_bps": 0,
           "rate_path": {
            "Q1": 0,
            "Q2": 0,
            "Q3": 0,
            "Q4": 0,
            "block_provenance": {}
           }
          },
          "recession": {
           "scenario": "string",
           "ma_scenario": "string",
           "probability": 0,
           "horizon": "string",
           "gdp_growth_pct": 0,
           "inflation_pct": 0,
           "unemployment_pct": 0,
           "policy_rate_pct": 0,
           "terminal_policy_rate_pct": 0,
           "yield_10y_pct": 0,
           "credit_spread_bps": 0,
           "rate_path": {
            "Q1": 0,
            "Q2": 0,
            "Q3": 0,
            "Q4": 0,
            "block_provenance": {}
           }
          },
          "tail": {
           "scenario": "string",
           "ma_scenario": "string",
           "probability": 0,
           "horizon": "string",
           "gdp_growth_pct": 0,
           "inflation_pct": 0,
           "unemployment_pct": 0,
           "policy_rate_pct": 0,
           "terminal_policy_rate_pct": 0,
           "yield_10y_pct": 0,
           "credit_spread_bps": 0,
           "rate_path": {
            "Q1": 0,
            "Q2": 0,
            "Q3": 0,
            "Q4": 0,
            "block_provenance": {}
           }
          }
         },
         "fx_context": {
          "EURUSD": {
           "valuation_band": "string",
           "misalignment_pct": 0,
           "carry_to_risk": 0,
           "risk_regime": "string",
           "data_source": "string",
           "source": "string",
           "as_of": "string",
           "as_of_basis": "string",
           "as_of_inputs": {
            "ecb_fx_sdw spot EURUSD": "string",
            "bis_cbpol EUR": "string",
            "bis_cbpol USD": "string",
            "bis_reer_broad EUR": "string",
            "bis_reer_broad USD": "string"
           },
           "verification_level": "string"
          },
          "GBPUSD": {
           "valuation_band": "string",
           "misalignment_pct": 0,
           "carry_to_risk": 0,
           "risk_regime": "string",
           "data_source": "string",
           "source": "string",
           "as_of": "string",
           "as_of_basis": "string",
           "as_of_inputs": {
            "ecb_fx_sdw spot GBPUSD": "string",
            "bis_cbpol GBP": "string",
            "bis_cbpol USD": "string",
            "bis_reer_broad GBP": "string",
            "bis_reer_broad USD": "string"
           },
           "verification_level": "string"
          },
          "USDJPY": {
           "valuation_band": "string",
           "misalignment_pct": 0,
           "carry_to_risk": 0,
           "risk_regime": "string",
           "data_source": "string",
           "source": "string",
           "as_of": "string",
           "as_of_basis": "string",
           "as_of_inputs": {
            "ecb_fx_sdw spot USDJPY": "string",
            "bis_cbpol USD": "string",
            "bis_cbpol JPY": "string",
            "bis_reer_broad USD": "string",
            "bis_reer_broad JPY": "string"
           },
           "verification_level": "string"
          }
         },
         "climate_paths": {
          "1.5C": {
           "probability": 0,
           "transition_risk_score": 0,
           "physical_risk_score": 0,
           "equity_impact_pct": 0,
           "bond_impact_pct": 0,
           "block_provenance": {
            "source": "string",
            "as_of": null,
            "level": null,
            "kind": "string",
            "covers": "string",
            "ref": "string",
            "method": "string"
           }
          },
          "2C": {
           "probability": 0,
           "transition_risk_score": 0,
           "physical_risk_score": 0,
           "equity_impact_pct": 0,
           "bond_impact_pct": 0,
           "block_provenance": {
            "source": "string",
            "as_of": null,
            "level": null,
            "kind": "string",
            "covers": "string",
            "ref": "string",
            "method": "string"
           }
          },
          "3C": {
           "probability": 0,
           "transition_risk_score": 0,
           "physical_risk_score": 0,
           "equity_impact_pct": 0,
           "bond_impact_pct": 0,
           "block_provenance": {
            "source": "string",
            "as_of": null,
            "level": null,
            "kind": "string",
            "covers": "string",
            "ref": "string",
            "method": "string"
           }
          },
          "current_policy": {
           "probability": 0,
           "transition_risk_score": 0,
           "physical_risk_score": 0,
           "equity_impact_pct": 0,
           "bond_impact_pct": 0,
           "block_provenance": {
            "source": "string",
            "as_of": null,
            "level": null,
            "kind": "string",
            "covers": "string",
            "ref": "string",
            "method": "string"
           }
          }
         },
         "provenance": {
          "as_of_basis": "string",
          "as_of_inputs": {
           "fred GDPC1": "string",
           "fred CPIAUCSL": "string",
           "fred FEDFUNDS": "string",
           "fred UNRATE": "string",
           "fred T10Y2Y": "string",
           "fx_context EURUSD": "string",
           "fx_context GBPUSD": "string",
           "fx_context USDJPY": "string"
          },
          "macro_source": "string",
          "macro_as_of": "string",
          "recession_methodology": "string",
          "recession_validation": {
           "probability_12m_raw": null,
           "model_feature_as_of": "string",
           "validation": {
            "published": {},
            "live": {},
            "honest_recursive_auc_band": [],
            "honest_recursive_auc_basis": "string"
           },
           "caveats": [
            "string"
           ],
           "feature_freshness": {
            "feature_as_of": "string",
            "state": "string",
            "behind_publisher_days": 0,
            "freshness_note": "string",
            "freshness_basis": "string",
            "judged_on": "string"
           },
           "probability_12m_raw_missing_reason": "string"
          },
          "fx_source": "string",
          "fx_pairs": [
           "string"
          ],
          "scenario_alias": "string",
          "bundle_interface": "string",
          "scenario_invariant_fields": [
           "string"
          ],
          "scenario_conditioning_scope": "string"
         },
         "notes": "string",
         "available_scenarios": [
          "string"
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "conditioning": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/conditioning",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/portfolio/rollup": {
   "get": {
    "summary": "Cross-vertical portfolio rollup (S4)",
    "description": "Read-only cross-vertical portfolio rollup (expected loss / concentration). Currently dark in the UI (PC uses predict/national instead).\n",
    "operationId": "getCrossPortfolioRollup",
    "tags": [
     "Cross-Vertical"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Cross-vertical portfolio rollup (S4)",
      "content": {
       "application/json": {
        "example": {
         "interface": "string",
         "scenario": "string",
         "as_of_date": "string",
         "as_of_basis": "string",
         "as_of_inputs": {
          "fred GDPC1": "string",
          "fred CPIAUCSL": "string",
          "fred FEDFUNDS": "string",
          "fred UNRATE": "string",
          "fred T10Y2Y": "string",
          "fx_context EURUSD": "string",
          "fx_context GBPUSD": "string",
          "fx_context USDJPY": "string"
         },
         "conditioning_applied": {
          "equity_return_pct": 0,
          "bond_return_pct": 0,
          "spread_widening_bps_vs_100": 0
         },
         "total_notional_usd": 0,
         "scenario_pnl_usd": 0,
         "scenario_return_pct": 0,
         "exposure_by_vertical": {
          "equities": 0,
          "private_credit": 0,
          "fixed_income": 0
         },
         "exposure_by_asset_class": {
          "equity": 0,
          "loan": 0,
          "bond": 0
         },
         "cross_vertical_concentration": [
          {
           "canonical_id": "string",
           "entity_key": "string",
           "verticals": [
            "string"
           ],
           "notional_usd": 0,
           "pct_of_book": 0,
           "positions": [
            "string"
           ]
          }
         ]
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "rollup": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "admin"
     ],
     "permissions": [
      "read_dashboard"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/portfolio/rollup",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": true,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/propagate": {
   "post": {
    "summary": "Propagate a signal across verticals (S4)",
    "description": "Propagates a shock/signal across verticals via the cross-vertical contagion graph (the S4 moat surface). Read-only over engines; additive and fail-safe.\n",
    "operationId": "postCrossPropagate",
    "tags": [
     "Cross-Vertical"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "source_vertical"
        ],
        "properties": {
         "source_vertical": {
          "type": "string"
         },
         "signal": {
          "type": "object"
         }
        }
       }
      }
     }
    },
    "responses": {
     "400": {
      "description": "Invalid request body"
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "410": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "route": "string",
         "since": "string",
         "ref": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "route_switched_off"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "retired",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": [
      "write_engines"
     ]
    },
    "deprecated": true,
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/propagate",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 410,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/billing/checkout": {
   "post": {
    "summary": "Create a Stripe Checkout session for any catalog plan",
    "description": "Creates a Stripe Checkout session for a plan in the published method note (explorer, professional, institutional, enterprise monthly or as published annually; the paid evaluation as a one-time payment with its agreed end date). The account and buyer email come from the signed-in session. Returns 503 (never a fabricated URL) when billing is not configured, 400 for an unknown plan or interval, 409 when the account already has an active subscription, 502 when Stripe errors.\n",
    "operationId": "postBillingCheckout",
    "tags": [
     "Billing"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "plan"
        ],
        "properties": {
         "plan": {
          "type": "string",
          "enum": [
           "explorer",
           "professional",
           "institutional",
           "enterprise",
           "evaluation"
          ]
         },
         "interval": {
          "type": "string",
          "enum": [
           "monthly",
           "annual",
           "one_time"
          ]
         },
         "ends_at": {
          "type": "string",
          "description": "Paid evaluation only - the agreed end date (YYYY-MM-DD)."
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Checkout session created",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "configured": {
           "type": "boolean"
          },
          "data": {
           "type": "object",
           "properties": {
            "checkout_url": {
             "type": "string"
            },
            "session_id": {
             "type": "string"
            },
            "plan": {
             "type": "string"
            },
            "interval": {
             "type": "string"
            },
            "mode": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown plan or interval, or missing evaluation end date",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "configured": false,
         "message": "string",
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "bad_request"
      ]
     },
     "409": {
      "description": "The account already has an active subscription"
     },
     "502": {
      "description": "Stripe returned an error"
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/billing/checkout",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 400,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/billing/portal": {
   "post": {
    "summary": "Open the Stripe customer portal for the signed-in account",
    "description": "Returns a Stripe customer-portal URL (update card, change or cancel the plan, invoices). 404 when nothing has been bought on the account yet; 503 when billing is not configured.\n",
    "operationId": "postBillingPortal",
    "tags": [
     "Billing"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Portal session created",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "data": {
           "type": "object",
           "properties": {
            "portal_url": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No billing account yet"
     },
     "503": {
      "description": "Billing not configured",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "configured": false,
         "message": "string",
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unavailable"
      ]
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/billing/portal",
      "role": "analyst",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/billing/entitlement": {
   "get": {
    "summary": "The signed-in account's plan and billing state",
    "description": "The account's plan, subscription state (none, trialing, active, past_due, canceled, paid, expired, or store_unavailable), whether that state grants access, what the plan unlocks, and whether billing is configured (test or live mode). Written only by the signed webhook.\n",
    "operationId": "getBillingEntitlement",
    "tags": [
     "Billing"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Plan and billing state",
      "content": {
       "application/json": {
        "example": {
         "entitlement": {
          "tenant_id": null,
          "state": "string",
          "plan": null,
          "interval": null,
          "grants": false,
          "unlocks": null,
          "current_period_end": null,
          "cancel_at_period_end": false,
          "has_billing_account": false,
          "livemode": null
         },
         "billing": {
          "sdk_installed": true,
          "mode": null,
          "checkout_available": false,
          "webhook_available": false
         }
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "entitlement": {
           "type": "object"
          },
          "billing": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "customer",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/billing/entitlement",
      "role": "analyst",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/billing/webhook": {
   "post": {
    "summary": "Stripe webhook receiver",
    "description": "Receives Stripe webhooks, verifying the Stripe-Signature header before trusting the payload. Rejects bad/missing signatures and events whose mode (test/live) does not match the server's key (400); returns 503 and processes nothing when billing is unconfigured or the billing store is unavailable. Applies checkout.session.completed, invoice.paid, invoice.payment_failed and customer.subscription.created/updated/deleted to the account's entitlement once per event id. No app auth (signature is the auth).\n",
    "operationId": "postBillingWebhook",
    "tags": [
     "Billing"
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Event verified and applied (or acknowledged as a duplicate / unhandled type)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid or missing signature, or event mode does not match the key"
     },
     "413": {
      "description": "Request body over the bound: 1 MiB on every route (10 MiB on /documents/upload); some routes take less (account flows 16 KiB, /api/v1/leads 32 KiB, the billing webhook 512 KiB). Answered with Connection: close.",
      "x-latavis-error-codes": [
       "payload_too_large"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Billing not configured or billing store unavailable",
      "content": {
       "application/json": {
        "example": {
         "ok": false,
         "configured": false,
         "message": "string",
         "error": "string",
         "code": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "unavailable"
      ]
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "411": {
      "description": "A request body sent with chunked transfer encoding and no Content-Length is refused before routing (Connection: close).",
      "x-latavis-error-codes": [
       "length_required"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "none",
     "roles": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "POST",
      "path": "/api/v1/billing/webhook",
      "role": "admin",
      "body": {},
      "skip_live": false
     },
     "status": 503,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/api/v1/_debug/sentry-test": {
   "get": {
    "summary": "Sentry wiring verification (guarded)",
    "description": "Raises a deliberate error to verify Sentry capture. Guarded: only live when a server setting is set, otherwise a no-op. Not for production traffic.\n",
    "operationId": "getSentryTest",
    "tags": [
     "Debug"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Sentry wiring verification (guarded)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "404": {
      "description": "Captured from the served API.",
      "content": {
       "application/json": {
        "example": {
         "error": "string",
         "code": "string",
         "status_code": 0
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      },
      "x-latavis-error-codes": [
       "debug_hook_disabled"
      ]
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "admin_ops"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/api/v1/_debug/sentry-test",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 404,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/compliance/soc2/dashboard": {
   "get": {
    "summary": "SOC 2 compliance dashboard (alias of status)",
    "description": "Alias of GET /compliance/soc2/status, returning the SOC 2 compliance dashboard summary.\n",
    "operationId": "getSoc2Dashboard",
    "tags": [
     "Compliance"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "SOC 2 compliance dashboard (alias of status)",
      "content": {
       "application/json": {
        "example": {
         "compliance_score": 0,
         "status": "string",
         "controls": {
          "total": 0,
          "passing": 0,
          "failing": 0,
          "degraded": 0
         },
         "gaps": {
          "total_gaps": 0,
          "remaining_gaps": 0,
          "target_completion": "string",
          "completion_percentage": 0
         },
         "message": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "admin"
     ],
     "permissions": [
      "read_audit"
     ]
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/compliance/soc2/dashboard",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  },
  "/validation/health": {
   "get": {
    "summary": "Validation module liveness",
    "description": "Liveness probe for the academic-validation module. Returns ok when the module is importable.\n",
    "operationId": "getValidationHealth",
    "tags": [
     "Validation"
    ],
    "security": [
     {
      "ApiKeyAuth": []
     },
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Validation module liveness",
      "content": {
       "application/json": {
        "example": {
         "status": "string",
         "module": "string"
        },
        "x-example-note": "Illustrative shape only: placeholder values, not served data (example fixed 2026-11-09). Figures in a real response carry their own source and as-of.",
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "module": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid credentials.",
      "x-latavis-error-codes": [
       "unauthenticated"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "403": {
      "description": "The key's role lacks the permission this route needs.",
      "x-latavis-error-codes": [
       "forbidden"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "405": {
      "description": "The path exists but not for this method (Allow header lists the methods).",
      "x-latavis-error-codes": [
       "method_not_allowed"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit or credit budget exceeded.",
      "x-latavis-error-codes": [
       "rate_limited"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "500": {
      "description": "A server fault (never a user mistake).",
      "x-latavis-error-codes": [
       "internal_error"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     },
     "503": {
      "description": "Engines warming, or a dependency unavailable (Retry-After when warming).",
      "x-latavis-error-codes": [
       "engine_warming",
       "unavailable"
      ],
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorBody"
        }
       }
      }
     }
    },
    "x-latavis-audience": "internal",
    "x-latavis-auth": {
     "scheme": "api_key",
     "roles": [
      "viewer",
      "analyst",
      "api_only",
      "admin"
     ],
     "permissions": []
    },
    "x-latavis-capture": {
     "request": {
      "method": "GET",
      "path": "/validation/health",
      "role": "admin",
      "body": null,
      "skip_live": false
     },
     "status": 200,
     "estate": false,
     "captured": "2026-10-31",
     "commit": "0a21c35"
    }
   }
  }
 },
 "security": [
  {
   "ApiKeyAuth": []
  }
 ]
}