{
  "openapi": "3.1.0",
  "info": {
    "title": "CallerScope API",
    "version": "2026-08-31",
    "description": "Tenant-scoped worldwide caller-intelligence API. Canonical, semantically valid human-dialable E.164 numbers are accepted independently of CallerScope evidence availability. Customer credentials are CallerScope keys; upstream NoCodeBackend secrets are never client credentials."
  },
  "servers": [{ "url": "https://callerscope.com" }],
  "tags": [
    { "name": "Numbers" },
    { "name": "Usage" },
    { "name": "API keys" },
    { "name": "Webhooks" }
  ],
  "paths": {
    "/api/v1/numbers/{e164}": {
      "get": {
        "operationId": "lookupNumber",
        "tags": ["Numbers"],
        "summary": "Look up one E.164 number",
        "security": [{ "callerScopeKey": [] }],
        "parameters": [
          {
            "name": "e164",
            "in": "path",
            "required": true,
            "schema": { "$ref": "#/components/schemas/E164" },
            "example": "+12025550100"
          }
        ],
        "responses": {
          "200": {
            "description": "Public, sanitized caller-intelligence result. A valid number with no qualified public evidence is not a safety finding, and provider dataset coverage is never implied.",
            "headers": {
              "X-CallerScope-API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "X-CallerScope-API-Deprecated": { "$ref": "#/components/headers/ApiDeprecated" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/NumberResponse" },
                "examples": {
                  "reservedUnknown": {
                    "value": {
                      "data": {
                        "e164": "+12025550100",
                        "validity": "valid",
                        "lookupEligibility": "eligible",
                        "numberingScope": "geographic",
                        "regionCode": "US",
                        "countryCallingCode": "1",
                        "formattedInternational": "+1 202 555 0100",
                        "formattedNational": "(202) 555-0100",
                        "numberType": "fixed_line_or_mobile",
                        "providerCoverage": "not_asserted",
                        "evidenceAvailability": "none",
                        "publicationStatus": "not_published",
                        "state": "unknown",
                        "severity": "none",
                        "confidence": "insufficient",
                        "freshness": "unknown",
                        "reasonCodes": ["NO_QUALIFIED_PUBLIC_EVIDENCE"],
                        "reportCount": 0,
                        "sourceCount": 0
                      },
                      "meta": { "requestId": "req_reserved_demo", "schemaVersion": 1 }
                    }
                  },
                  "globalServiceUnknown": {
                    "value": {
                      "data": {
                        "e164": "+80012345678",
                        "validity": "valid",
                        "lookupEligibility": "eligible",
                        "numberingScope": "non_geographic",
                        "regionCode": null,
                        "countryCallingCode": "800",
                        "formattedInternational": "+800 1234 5678",
                        "formattedNational": null,
                        "numberType": "toll_free",
                        "providerCoverage": "not_asserted",
                        "evidenceAvailability": "none",
                        "publicationStatus": "not_published",
                        "state": "unknown",
                        "severity": "none",
                        "confidence": "insufficient",
                        "freshness": "unknown",
                        "reasonCodes": ["NO_QUALIFIED_PUBLIC_EVIDENCE"],
                        "reportCount": 0,
                        "sourceCount": 0
                      },
                      "meta": { "requestId": "req_global_service", "schemaVersion": 1 }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/v1/numbers/batch": {
      "post": {
        "operationId": "lookupNumberBatch",
        "tags": ["Numbers"],
        "summary": "Look up 1–25 E.164 numbers",
        "description": "Input order and duplicates are preserved. Tenant and key quota are reserved atomically by item count before any lookup runs.",
        "security": [{ "callerScopeKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["numbers"],
                "properties": {
                  "numbers": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "items": { "$ref": "#/components/schemas/E164" }
                  }
                }
              },
              "example": { "numbers": ["+12025550100", "+12025550101"] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order-preserving per-item results. A provider failure is isolated to its item.",
            "headers": {
              "X-CallerScope-API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "X-CallerScope-API-Deprecated": { "$ref": "#/components/headers/ApiDeprecated" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "operationId": "getUsage",
        "tags": ["Usage"],
        "summary": "Read tenant-scoped usage",
        "description": "Requires usage:read. Defaults to the preceding 30 days. Explicit windows are half-open [from, to), span at most 93x24 hours, and can touch at most 94 UTC calendar dates.",
        "security": [{ "callerScopeKey": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" }
        ],
        "responses": {
          "200": {
            "description": "Usage for the API key's organization and environment only.",
            "headers": {
              "X-CallerScope-API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "X-CallerScope-API-Deprecated": { "$ref": "#/components/headers/ApiDeprecated" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/UsageAggregate" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/v1/keys": {
      "get": {
        "operationId": "listApiKeys",
        "tags": ["API keys"],
        "summary": "List organization API keys",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "200": { "$ref": "#/components/responses/KeyList" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "tags": ["API keys"],
        "summary": "Create a scoped CallerScope key",
        "description": "Requires an organization-admin session, recent authentication, CSRF protection and idempotency. Clear key material is returned only by this retry-stable response window.",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateApiKey" }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/KeyCreated" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "422": { "$ref": "#/components/responses/Unprocessable" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/keys/{id}/rotate": {
      "post": {
        "operationId": "rotateApiKey",
        "tags": ["API keys"],
        "summary": "Rotate a CallerScope key",
        "description": "The previous key remains valid for a server-owned 24-hour overlap.",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 } }
              }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/KeyCreated" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/keys/{id}/revoke": {
      "post": {
        "operationId": "revokeApiKey",
        "tags": ["API keys"],
        "summary": "Revoke a CallerScope key",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
        "responses": {
          "200": { "description": "Key revoked." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "operationId": "listWebhookEndpoints",
        "tags": ["Webhooks"],
        "summary": "List tenant webhook endpoints",
        "security": [{ "sessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Environment" }],
        "responses": {
          "200": {
            "description": "Secret hashes and overlap material are never returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items", "meta"],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/WebhookEndpoint" }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "operationId": "createWebhookEndpoint",
        "tags": ["Webhooks"],
        "summary": "Create a webhook endpoint",
        "description": "Maximum 10 active endpoints per organization and environment. Only public HTTPS port-443 targets are accepted. Before outbound delivery can be activated, the delivery runtime must re-resolve and validate DNS at connection time, reject redirects, and enforce the documented retry and dead-letter policy.",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateWebhook" }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/WebhookSecretCreated" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "422": { "$ref": "#/components/responses/Unprocessable" }
        }
      }
    },
    "/api/v1/webhooks/{id}/rotate": {
      "post": {
        "operationId": "rotateWebhookSecret",
        "tags": ["Webhooks"],
        "summary": "Rotate a webhook signing secret",
        "description": "The prior secret remains valid for a server-owned 24-hour overlap.",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VersionedEnvironment" }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/WebhookSecretCreated" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/v1/webhooks/{id}": {
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "tags": ["Webhooks"],
        "summary": "Delete a webhook endpoint",
        "security": [{ "sessionCookie": [], "csrfToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ResourceId" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VersionedEnvironment" }
            }
          }
        },
        "responses": {
          "200": { "description": "Endpoint tombstoned and future delivery suppressed." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "callerScopeKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cs_live_…" },
      "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-callerscope_session" },
      "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token" }
    },
    "headers": {
      "ApiVersion": { "schema": { "type": "string", "const": "2026-08-31" } },
      "ApiDeprecated": { "schema": { "type": "string", "const": "false" } }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "X-Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }
      },
      "ResourceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }
      },
      "Environment": {
        "name": "environment",
        "in": "query",
        "required": true,
        "schema": { "$ref": "#/components/schemas/Environment" }
      },
      "From": {
        "name": "from",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "format": "date-time" }
      },
      "To": {
        "name": "to",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "format": "date-time" }
      }
    },
    "schemas": {
      "E164": {
        "type": "string",
        "pattern": "^\\+[1-9][0-9]{6,14}$",
        "description": "Structurally canonical E.164 (7–15 digits including the country calling code). Routes additionally require current semantic validity."
      },
      "Environment": { "type": "string", "enum": ["test", "live"] },
      "Meta": {
        "type": "object",
        "additionalProperties": false,
        "required": ["requestId", "schemaVersion"],
        "properties": {
          "requestId": { "type": "string" },
          "schemaVersion": { "type": "integer", "const": 1 }
        }
      },
      "NumberResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "e164",
          "validity",
          "lookupEligibility",
          "numberingScope",
          "regionCode",
          "countryCallingCode",
          "formattedInternational",
          "formattedNational",
          "numberType",
          "providerCoverage",
          "evidenceAvailability",
          "publicationStatus",
          "state",
          "severity",
          "confidence",
          "freshness",
          "reasonCodes",
          "reportCount",
          "sourceCount"
        ],
        "properties": {
          "e164": { "$ref": "#/components/schemas/E164" },
          "validity": {
            "type": "string",
            "const": "valid",
            "description": "Semantic validity of the canonical number; invalid inputs receive 422."
          },
          "lookupEligibility": {
            "type": "string",
            "const": "eligible",
            "description": "CallerScope accepts this valid number for lookup, independently of evidence."
          },
          "numberingScope": {
            "type": "string",
            "enum": ["geographic", "non_geographic"]
          },
          "regionCode": {
            "type": ["string", "null"],
            "pattern": "^[A-Z]{2}$",
            "description": "ISO region when resolved; null for non-geographic codes and unresolved shared geographic numbering plans."
          },
          "countryCallingCode": { "type": "string", "pattern": "^[1-9][0-9]{0,2}$" },
          "formattedInternational": { "type": "string", "minLength": 1, "maxLength": 32 },
          "formattedNational": {
            "type": ["string", "null"],
            "minLength": 1,
            "maxLength": 32,
            "description": "National display form when available; null for non-geographic numbers and unresolved shared plans."
          },
          "numberType": {
            "type": "string",
            "enum": [
              "fixed_line",
              "mobile",
              "fixed_line_or_mobile",
              "toll_free",
              "premium_rate",
              "shared_cost",
              "voip",
              "personal_number",
              "pager",
              "uan",
              "voicemail",
              "unknown"
            ]
          },
          "providerCoverage": {
            "type": "string",
            "const": "not_asserted",
            "description": "No claim is made about any upstream provider's dataset coverage."
          },
          "evidenceAvailability": {
            "type": "string",
            "enum": ["none", "qualified_public"],
            "description": "Availability of qualified CallerScope public evidence, not number safety. Qualified means one or more approved reports with coherent independent source-family evidence. When none, the result is always unknown with severity none, insufficient confidence and unknown freshness; an optional verified-business identity is not reputation evidence."
          },
          "publicationStatus": {
            "type": "string",
            "enum": ["not_published", "published"]
          },
          "state": {
            "type": "string",
            "enum": [
              "unknown",
              "limited",
              "nuisance",
              "suspicious",
              "high_risk",
              "mixed",
              "verified_business",
              "stale"
            ]
          },
          "severity": { "type": "string", "enum": ["none", "low", "medium", "high"] },
          "confidence": { "type": "string", "enum": ["insufficient", "low", "medium", "high"] },
          "freshness": { "type": "string", "enum": ["current", "aging", "stale", "unknown"] },
          "reasonCodes": { "type": "array", "items": { "type": "string" } },
          "reportCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Safe-integer approved public report count. Qualified evidence requires at least one; stronger confidence and risk bands have higher necessary minima."
          },
          "sourceCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Unique independent source-family count, never a count of provider or phone-number types."
          },
          "updatedAt": { "type": "string", "format": "date-time" },
          "verifiedBusiness": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name", "publicId"],
            "properties": {
              "name": { "type": "string", "minLength": 1, "maxLength": 160 },
              "publicId": { "type": "string", "format": "uuid" }
            }
          }
        },
        "allOf": [
          {
            "if": {
              "type": "object",
              "properties": { "numberingScope": { "const": "non_geographic" } },
              "required": ["numberingScope"]
            },
            "then": {
              "type": "object",
              "properties": {
                "regionCode": { "type": "null" },
                "formattedNational": { "type": "null" }
              }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "evidenceAvailability": { "const": "none" } },
              "required": ["evidenceAvailability"]
            },
            "then": {
              "type": "object",
              "properties": {
                "state": { "const": "unknown" },
                "severity": { "const": "none" },
                "confidence": { "const": "insufficient" },
                "freshness": { "const": "unknown" },
                "reportCount": { "const": 0 },
                "sourceCount": { "const": 0 }
              }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "evidenceAvailability": { "const": "qualified_public" } },
              "required": ["evidenceAvailability"]
            },
            "then": {
              "type": "object",
              "properties": {
                "publicationStatus": { "const": "published" },
                "reportCount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
                "sourceCount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
              }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "confidence": { "const": "medium" } },
              "required": ["confidence"]
            },
            "then": {
              "type": "object",
              "properties": { "reportCount": { "type": "integer", "minimum": 2 } }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "confidence": { "const": "high" } },
              "required": ["confidence"]
            },
            "then": {
              "type": "object",
              "properties": { "reportCount": { "type": "integer", "minimum": 3 } }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "state": { "enum": ["mixed", "suspicious"] } },
              "required": ["state"]
            },
            "then": {
              "type": "object",
              "properties": { "reportCount": { "type": "integer", "minimum": 2 } }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": { "state": { "const": "high_risk" } },
              "required": ["state"]
            },
            "then": {
              "type": "object",
              "properties": {
                "reportCount": { "type": "integer", "minimum": 3 },
                "severity": { "enum": ["high"] },
                "confidence": { "enum": ["medium", "high"] }
              }
            }
          },
          {
            "if": {
              "type": "object",
              "properties": {
                "evidenceAvailability": { "const": "none" },
                "publicationStatus": { "const": "published" }
              },
              "required": ["evidenceAvailability", "publicationStatus"]
            },
            "then": { "type": "object", "required": ["verifiedBusiness"] }
          }
        ]
      },
      "NumberResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "meta"],
        "properties": {
          "data": { "$ref": "#/components/schemas/NumberResult" },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "BatchItem": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["index", "e164", "data"],
            "properties": {
              "index": { "type": "integer", "minimum": 0, "maximum": 24 },
              "e164": { "$ref": "#/components/schemas/E164" },
              "data": { "$ref": "#/components/schemas/NumberResult" }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["index", "e164", "error"],
            "properties": {
              "index": { "type": "integer", "minimum": 0, "maximum": 24 },
              "e164": { "$ref": "#/components/schemas/E164" },
              "error": {
                "type": "object",
                "required": ["code", "message"],
                "properties": {
                  "code": { "type": "string", "const": "LOOKUP_TEMPORARILY_UNAVAILABLE" },
                  "message": { "type": "string" }
                }
              }
            }
          }
        ]
      },
      "BatchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "minItems": 1,
                "maxItems": 25,
                "items": { "$ref": "#/components/schemas/BatchItem" }
              }
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": ["requestId", "schemaVersion", "total", "succeeded", "failed"],
            "properties": {
              "requestId": { "type": "string" },
              "schemaVersion": { "type": "integer", "const": 1 },
              "total": { "type": "integer", "minimum": 1, "maximum": 25 },
              "succeeded": { "type": "integer", "minimum": 0, "maximum": 25 },
              "failed": { "type": "integer", "minimum": 0, "maximum": 25 }
            }
          }
        }
      },
      "UsageCounters": {
        "type": "object",
        "additionalProperties": false,
        "required": ["lookupUnits", "successfulRequests", "rejectedRequests", "providerFailures"],
        "properties": {
          "lookupUnits": { "type": "integer", "minimum": 0 },
          "successfulRequests": { "type": "integer", "minimum": 0 },
          "rejectedRequests": { "type": "integer", "minimum": 0 },
          "providerFailures": { "type": "integer", "minimum": 0 }
        }
      },
      "UsageAggregate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "organizationId",
          "environment",
          "from",
          "to",
          "generatedAt",
          "totals",
          "days"
        ],
        "properties": {
          "organizationId": { "type": "string" },
          "environment": { "$ref": "#/components/schemas/Environment" },
          "from": { "type": "string", "format": "date-time" },
          "to": { "type": "string", "format": "date-time" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "totals": { "$ref": "#/components/schemas/UsageCounters" },
          "days": {
            "type": "array",
            "maxItems": 94,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "date",
                "lookupUnits",
                "successfulRequests",
                "rejectedRequests",
                "providerFailures"
              ],
              "properties": {
                "date": { "type": "string", "format": "date" },
                "lookupUnits": { "type": "integer", "minimum": 0 },
                "successfulRequests": { "type": "integer", "minimum": 0 },
                "rejectedRequests": { "type": "integer", "minimum": 0 },
                "providerFailures": { "type": "integer", "minimum": 0 }
              }
            }
          }
        }
      },
      "ApiKeyRecord": {
        "type": "object",
        "additionalProperties": false,
        "description": "Public key metadata. The digest is never included.",
        "required": [
          "id",
          "organizationId",
          "applicationId",
          "name",
          "environment",
          "prefix",
          "lastFour",
          "scopes",
          "rotationGroupId",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string" },
          "organizationId": { "type": "string" },
          "applicationId": { "type": "string" },
          "name": { "type": "string" },
          "environment": { "$ref": "#/components/schemas/Environment" },
          "prefix": { "type": "string", "enum": ["cs_test_", "cs_live_"] },
          "lastFour": { "type": "string", "minLength": 4, "maxLength": 4 },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "keyQuotaPerMinute": { "type": "integer", "minimum": 1 },
          "rotationGroupId": { "type": "string" },
          "rotatedFromKeyId": { "type": "string" },
          "replacedByKeyId": { "type": "string" },
          "rotationOverlapEndsAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "revokedAt": { "type": "string", "format": "date-time" }
        }
      },
      "CreateApiKey": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "applicationId", "environment", "scopes"],
        "properties": {
          "name": { "type": "string", "minLength": 2, "maxLength": 80 },
          "applicationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{3,80}$" },
          "environment": { "$ref": "#/components/schemas/Environment" },
          "scopes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": { "type": "string" }
          },
          "keyQuotaPerMinute": { "type": "integer", "minimum": 1 },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookEventType": {
        "type": "string",
        "enum": [
          "number.assessment.changed",
          "number.severe_evidence.corroborated",
          "business.verification.changed",
          "remedy.outcome.changed"
        ]
      },
      "WebhookEndpoint": {
        "type": "object",
        "additionalProperties": false,
        "description": "Public endpoint metadata. Secret hashes and previous-secret overlap values are omitted.",
        "required": [
          "id",
          "organizationId",
          "environment",
          "name",
          "url",
          "eventTypes",
          "secretLastFour",
          "createdAt",
          "updatedAt",
          "version"
        ],
        "properties": {
          "id": { "type": "string" },
          "organizationId": { "type": "string" },
          "environment": { "$ref": "#/components/schemas/Environment" },
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri", "pattern": "^https://" },
          "eventTypes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/WebhookEventType" }
          },
          "secretLastFour": { "type": "string", "minLength": 4, "maxLength": 4 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "rotatedAt": { "type": "string", "format": "date-time" },
          "deletedAt": { "type": "string", "format": "date-time" },
          "version": { "type": "integer", "minimum": 1 }
        }
      },
      "CreateWebhook": {
        "type": "object",
        "additionalProperties": false,
        "required": ["environment", "name", "url", "eventTypes"],
        "properties": {
          "environment": { "$ref": "#/components/schemas/Environment" },
          "name": { "type": "string", "minLength": 2, "maxLength": 80 },
          "url": { "type": "string", "format": "uri", "pattern": "^https://" },
          "eventTypes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "uniqueItems": true,
            "items": { "$ref": "#/components/schemas/WebhookEventType" }
          }
        }
      },
      "VersionedEnvironment": {
        "type": "object",
        "additionalProperties": false,
        "required": ["environment", "expectedVersion"],
        "properties": {
          "environment": { "$ref": "#/components/schemas/Environment" },
          "expectedVersion": { "type": "integer", "minimum": 1 }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "requestId"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "requestId": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "KeyList": {
        "description": "Tenant-scoped key metadata.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ApiKeyRecord" }
                }
              }
            }
          }
        }
      },
      "KeyCreated": {
        "description": "Clear key material is present only in this retry-stable response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["key", "keyRecord", "warning"],
              "properties": {
                "key": { "type": "string", "readOnly": true, "format": "password" },
                "keyRecord": { "$ref": "#/components/schemas/ApiKeyRecord" },
                "warning": { "type": "string" }
              }
            }
          }
        }
      },
      "WebhookSecretCreated": {
        "description": "Clear signing secret is present only in this retry-stable response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["endpoint", "secret", "warning"],
              "properties": {
                "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" },
                "secret": {
                  "type": "string",
                  "readOnly": true,
                  "format": "password",
                  "pattern": "^cs_whsec_[a-f0-9]{48}$"
                },
                "previousSecretValidUntil": { "type": "string", "format": "date-time" },
                "warning": { "type": "string" }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Malformed or ambiguous request.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Authentication failed.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "Scope, entitlement, CSRF, origin or recent-auth requirement failed.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found in the authenticated tenant.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Conflict": {
        "description": "Version, idempotency or resource-state conflict.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unprocessable": {
        "description": "Validation failed.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Request or lookup-unit quota exceeded.",
        "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "Feature kill switch or provider readiness blocked the operation.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}