openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Callora API",
    "version": "1.0.0",
    "description": "API contract covering Callora backend billing, usage, and developer routes."
  },
  "paths": {
    "/api/vault/balance": {
      "get": {
        "summary": "Get the authenticated user's vault balance",
        "operationId": "getVaultBalance",
        "description": "Returns the latest cached balance snapshot. Snapshots older than VAULT_SNAPSHOT_MAX_AGE_MS are refreshed from the read-only vault contract; if Soroban RPC is unavailable, the previous value is returned with stale=true.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "network",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "testnet",
                "mainnet"
              ]
            },
            "description": "Stellar network. Defaults to the configured active network."
          }
        ],
        "responses": {
          "200": {
            "description": "Vault balance snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data",
                    "requestId",
                    "timestamp"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "balance_usdc",
                        "contractId",
                        "network",
                        "lastSyncedAt",
                        "stale"
                      ],
                      "properties": {
                        "balance_usdc": {
                          "type": "string",
                          "pattern": "^-?\\d+\\.\\d{7}$"
                        },
                        "contractId": {
                          "type": "string"
                        },
                        "network": {
                          "type": "string",
                          "enum": [
                            "testnet",
                            "mainnet"
                          ]
                        },
                        "lastSyncedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "stale": {
                          "type": "boolean"
                        }
                      }
                    },
                    "requestId": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The caller has no vault on the requested network",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/vault/onchain": {
      "get": {
        "summary": "Read live on-chain vault state",
        "operationId": "getOnchainVaultState",
        "description": "Simulates the vault's read-only view functions and returns their values at the indicated ledger. In DEMO_MODE, requests without authentication read the configured testnet vault.",
        "security": [
          {},
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "network",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "testnet",
                "mainnet"
              ]
            },
            "description": "Stellar network. Defaults to the configured active network."
          }
        ],
        "responses": {
          "200": {
            "description": "Live on-chain vault state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data",
                    "requestId",
                    "timestamp"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "contractId",
                        "network",
                        "balanceUsdc",
                        "maxDeductUsdc",
                        "paused",
                        "usdcToken",
                        "settlement",
                        "ledger"
                      ],
                      "properties": {
                        "contractId": {
                          "type": "string"
                        },
                        "network": {
                          "type": "string",
                          "enum": [
                            "testnet",
                            "mainnet"
                          ]
                        },
                        "balanceUsdc": {
                          "type": "string",
                          "pattern": "^-?\\d+\\.\\d{7}$"
                        },
                        "maxDeductUsdc": {
                          "type": "string",
                          "pattern": "^-?\\d+\\.\\d{7}$"
                        },
                        "paused": {
                          "type": "boolean"
                        },
                        "usdcToken": {
                          "type": "string"
                        },
                        "settlement": {
                          "type": "string"
                        },
                        "ledger": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    },
                    "requestId": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required outside the public demo mode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The caller has no vault on the requested network",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/billing/credits/grant": {
      "post": {
        "summary": "Grant GrantFox FWC26 prepaid credits",
        "description": "Adds prepaid USDC credits to a user account for the GrantFox FWC26 campaign. Requires admin authentication and the admin IP allowlist.",
        "security": [
          {
            "adminApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "user_id",
                  "amount_usdc"
                ],
                "properties": {
                  "user_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "amount_usdc": {
                    "type": "string",
                    "pattern": "^\\d+(?:\\.\\d{1,7})?$",
                    "description": "Positive USDC amount with at most seven fractional digits"
                  }
                }
              },
              "example": {
                "user_id": "user_123",
                "amount_usdc": "25.50"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Credits granted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "user_id",
                        "amount_usdc",
                        "balance_usdc",
                        "campaign",
                        "updated_at"
                      ],
                      "properties": {
                        "user_id": {
                          "type": "string"
                        },
                        "amount_usdc": {
                          "type": "string"
                        },
                        "balance_usdc": {
                          "type": "string"
                        },
                        "campaign": {
                          "type": "string",
                          "example": "GrantFox FWC26"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid grant request"
          },
          "401": {
            "description": "Unauthorized admin request"
          },
          "403": {
            "description": "Forbidden by admin IP allowlist"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Application health check",
        "description": "Returns the health status of the application and its dependencies (database, Soroban RPC, Horizon). Public endpoint — no authentication required.",
        "tags": [
          "Health"
        ],
        "responses": {
          "200": {
            "description": "Application is healthy or partially degraded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "examples": {
                  "simpleOk": {
                    "summary": "Simple health check (no config)",
                    "value": {
                      "success": true,
                      "data": {
                        "status": "ok",
                        "service": "callora-backend"
                      },
                      "requestId": "req-mock-uuid",
                      "timestamp": "2026-07-25T10:00:00.000Z"
                    }
                  },
                  "fullOk": {
                    "summary": "Full health check — all dependencies healthy",
                    "value": {
                      "success": true,
                      "data": {
                        "status": "ok",
                        "version": "1.0.0",
                        "timestamp": "2026-07-25T10:00:00.000Z",
                        "checks": {
                          "api": "ok",
                          "database": "ok",
                          "soroban_rpc": "ok"
                        }
                      },
                      "requestId": "req-mock-uuid",
                      "timestamp": "2026-07-25T10:00:00.000Z"
                    }
                  },
                  "degraded": {
                    "summary": "Degraded — database slow, optional dep down",
                    "value": {
                      "success": true,
                      "data": {
                        "status": "degraded",
                        "version": "1.0.0",
                        "timestamp": "2026-07-25T10:00:00.000Z",
                        "checks": {
                          "api": "ok",
                          "database": "degraded",
                          "soroban_rpc": "down"
                        }
                      },
                      "requestId": "req-mock-uuid",
                      "timestamp": "2026-07-25T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Application is down or health check failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "serviceUnavailable": {
                    "summary": "Health check failure",
                    "value": {
                      "code": "SERVICE_UNAVAILABLE",
                      "message": "Health check failed",
                      "requestId": "req-mock-uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health/health": {
      "get": {
        "summary": "Health Dependency Probe",
        "description": "A dependency-level health probe that enumerates configured external dependencies (database, Soroban RPC, Horizon) with individual status, response time, and sanitized error information.",
        "tags": [
          "Health"
        ],
        "responses": {
          "200": {
            "description": "Dependencies are healthy or partially degraded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "503": {
            "description": "Dependencies are down or probe failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/rate-limit/health": {
      "get": {
        "summary": "Check rate-limit subsystem health",
        "description": "Returns the operational status of the rate-limit subsystem and its configured dependencies. This public probe does not consume rate-limit budget and does not require a request body.",
        "responses": {
          "200": {
            "description": "Rate-limit subsystem is operational",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitHealthResponse"
                },
                "examples": {
                  "operational": {
                    "summary": "In-memory limiter is operational",
                    "value": {
                      "status": "ok",
                      "timestamp": "2026-07-28T10:00:00.000Z",
                      "dependencies": {
                        "in_memory_store": {
                          "status": "ok",
                          "responseTime": 0.123,
                          "details": {
                            "windowMs": 60000,
                            "maxRequests": 100
                          }
                        }
                      }
                    }
                  },
                  "notConfigured": {
                    "summary": "No limiter configured",
                    "value": {
                      "status": "ok",
                      "timestamp": "2026-07-28T10:00:00.000Z",
                      "dependencies": {
                        "in_memory_store": {
                          "status": "ok",
                          "details": {
                            "note": "No rate limiter configured for probing"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Rate-limit subsystem is unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitHealthResponse"
                },
                "examples": {
                  "unavailable": {
                    "summary": "Rate-limit store probe failed",
                    "value": {
                      "status": "down",
                      "timestamp": "2026-07-28T10:00:00.000Z",
                      "dependencies": {
                        "in_memory_store": {
                          "status": "down",
                          "responseTime": 0.456,
                          "error": "unavailable"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/limits/check": {
      "get": {
        "summary": "Check the authenticated user's rate-limit budget",
        "description": "Peeks at the authenticated user's REST rate-limit bucket without consuming a token. No request body is required.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Rate-limit budget status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitCheckResponse"
                },
                "examples": {
                  "allowed": {
                    "summary": "Requests are currently allowed",
                    "value": {
                      "status": "ok"
                    }
                  },
                  "denied": {
                    "summary": "Rate-limit budget is exhausted",
                    "value": {
                      "status": "deny",
                      "reason": "rate_limit_exceeded",
                      "retryAfterMs": 42300
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Authentication required",
                      "requestId": "req-rate-limit-check"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/gateway/health/{apiSlug}": {
      "get": {
        "summary": "Get gateway health for an API",
        "description": "Returns aggregated upstream latency percentiles and circuit breaker state for a given API slug. Public endpoint — no authentication required. Only aggregated metrics are returned; no tenant identifiers or raw histogram data are exposed. Results are cached in-memory for 5 seconds.",
        "parameters": [
          {
            "name": "apiSlug",
            "in": "path",
            "required": true,
            "description": "The API slug to query health for",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Health data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayHealthResponse"
                }
              }
            }
          },
          "404": {
            "description": "API slug not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/deduct": {
      "post": {
        "summary": "Deduct billing balance for an API call",
        "description": "Deducts USDC from the user's vault balance to pay for an API call. Authenticated and idempotent.",
        "externalDocs": {
          "description": "SDK idempotency contract and retry guidance",
          "url": "https://callora.com/sdk/billing-deduct.md"
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingDeductRequest"
              },
              "examples": {
                "deductRequest": {
                  "summary": "Deduct billing request",
                  "value": {
                    "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
                    "developerId": "dev-123",
                    "apiId": "api-123",
                    "endpointId": "endpoint-456",
                    "apiKeyId": "key-789",
                    "amountUsdc": "0.01",
                    "idempotencyKey": "idem-abc123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Billing deduction successfully processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingDeductResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful deduction",
                    "value": {
                      "success": true,
                      "usageEventId": "evt-123e4567-e89b-12d3-a456-426614174000",
                      "stellarTxHash": "abc123def456...",
                      "alreadyProcessed": false
                    }
                  },
                  "alreadyProcessed": {
                    "summary": "Already processed (idempotent)",
                    "value": {
                      "success": true,
                      "usageEventId": "evt-123e4567-e89b-12d3-a456-426614174000",
                      "stellarTxHash": "abc123def456...",
                      "alreadyProcessed": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidAmount": {
                    "summary": "Invalid amount format",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "amountUsdc must be a positive number with at most 7 decimal places",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Authentication required",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required (insufficient balance)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "insufficientBalance": {
                    "summary": "Insufficient balance",
                    "value": {
                      "code": "INSUFFICIENT_BALANCE",
                      "message": "Vault balance too low for deduction",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict or reconciliation required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "idempotencyConflict": {
                    "summary": "Idempotency key already used with different parameters",
                    "value": {
                      "code": "IDEMPOTENCY_CONFLICT",
                      "message": "Idempotency key conflict: different request parameters",
                      "requestId": "req-abc123"
                    }
                  },
                  "reconciliationRequired": {
                    "summary": "Previous deduction attempt pending reconciliation",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "RECONCILIATION_REQUIRED",
                        "message": "Billing deduction pending reconciliation"
                      },
                      "reconciliationRequired": true,
                      "deductionStatus": "pending",
                      "usageEventId": "evt-123",
                      "requestId": "req-abc123",
                      "timestamp": "2026-07-28T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/deduct/bulk": {
      "post": {
        "summary": "Deduct billing balance for up to 100 API calls in one batch",
        "description": "Creates usage events for up to 100 billing entries in a single database transaction, then performs one aggregate on-chain deduction for the newly inserted entries. Existing requestIds are treated idempotently and are returned in the per-entry results without being charged again.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional key for replaying the complete batch response."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingBulkDeductRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk billing deduction successfully processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingBulkDeductResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid batch or duplicate requestId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingBulkDeductErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Aggregate balance is insufficient; no new usage events are charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency key conflict or deduction requires reconciliation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingBulkDeductErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "description": "Seconds until the rate limit expires"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "rateLimited": {
                    "summary": "Too many requests",
                    "value": {
                      "code": "TOO_MANY_REQUESTS",
                      "message": "Too Many Requests",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/usage": {
      "get": {
        "summary": "Retrieve user API usage and stats",
        "description": "Returns the authenticated user's API call events, aggregated stats, and time breakdown.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start of period (ISO-8601 string)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End of period (ISO-8601 string)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of usage events to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "apiId",
            "in": "query",
            "description": "Filter by specific API ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "groupBy",
            "in": "query",
            "description": "Aggregation bucket size",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage events and analytics retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                },
                "examples": {
                  "withEvents": {
                    "summary": "Typical response with two usage events",
                    "value": {
                      "events": [
                        {
                          "id": "evt_01hx9r2k3m4n5p6q7r8s9t0u",
                          "apiId": "api_weather_v1",
                          "endpoint": "/v1/weather/current",
                          "occurredAt": "2026-07-01T14:32:00.000Z",
                          "revenue": "1000000"
                        },
                        {
                          "id": "evt_01hx9r2k3m4n5p6q7r8s9t0v",
                          "apiId": "api_weather_v1",
                          "endpoint": "/v1/weather/forecast",
                          "occurredAt": "2026-07-01T14:45:00.000Z",
                          "revenue": "1000000"
                        }
                      ],
                      "stats": {
                        "totalCalls": 2,
                        "totalSpent": "2000000",
                        "breakdownByApi": [
                          {
                            "apiId": "api_weather_v1",
                            "calls": 2,
                            "revenue": "2000000"
                          }
                        ]
                      },
                      "period": {
                        "from": "2026-06-01T00:00:00.000Z",
                        "to": "2026-07-01T00:00:00.000Z"
                      },
                      "pagination": {
                        "limit": 20,
                        "offset": 0,
                        "hasMore": false
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t0w"
                    }
                  },
                  "withBuckets": {
                    "summary": "Response with daily call buckets (groupBy=day)",
                    "value": {
                      "events": [
                        {
                          "id": "evt_01hx9r2k3m4n5p6q7r8s9t0x",
                          "apiId": "api_maps_v2",
                          "endpoint": "/v2/geocode",
                          "occurredAt": "2026-07-10T09:15:00.000Z",
                          "revenue": "500000"
                        }
                      ],
                      "stats": {
                        "totalCalls": 1,
                        "totalSpent": "500000",
                        "breakdownByApi": [
                          {
                            "apiId": "api_maps_v2",
                            "calls": 1,
                            "revenue": "500000"
                          }
                        ],
                        "buckets": [
                          {
                            "period": "2026-07-10",
                            "calls": 1,
                            "revenue": "500000"
                          }
                        ]
                      },
                      "period": {
                        "from": "2026-07-10T00:00:00.000Z",
                        "to": "2026-07-11T00:00:00.000Z"
                      },
                      "pagination": {
                        "limit": 20,
                        "offset": 0,
                        "hasMore": false
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t0y"
                    }
                  },
                  "empty": {
                    "summary": "No events in the requested period",
                    "value": {
                      "events": [],
                      "stats": {
                        "totalCalls": 0,
                        "totalSpent": "0",
                        "breakdownByApi": []
                      },
                      "period": {
                        "from": "2026-06-01T00:00:00.000Z",
                        "to": "2026-07-01T00:00:00.000Z"
                      },
                      "pagination": {
                        "limit": 20,
                        "offset": 0,
                        "hasMore": false
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t0z"
                    }
                  },
                  "withCursorPagination": {
                    "summary": "Cursor-paginated response (more pages available)",
                    "value": {
                      "events": [
                        {
                          "id": "evt_01hx9r2k3m4n5p6q7r8s9t1a",
                          "apiId": "api_translate_v1",
                          "endpoint": "/v1/translate",
                          "occurredAt": "2026-07-20T11:00:00.000Z",
                          "revenue": "250000"
                        }
                      ],
                      "stats": {
                        "totalCalls": 1,
                        "totalSpent": "250000",
                        "breakdownByApi": [
                          {
                            "apiId": "api_translate_v1",
                            "calls": 1,
                            "revenue": "250000"
                          }
                        ]
                      },
                      "period": {
                        "from": "2026-07-01T00:00:00.000Z",
                        "to": "2026-07-31T00:00:00.000Z"
                      },
                      "pagination": {
                        "limit": 1,
                        "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yMFQxMTowMDowMC4wMDBaIiwiaWQiOiJldnRfMDFoeDlyMmszbTRuNXA2cTdyOHM5dDF"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1b"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidDateRange": {
                    "summary": "from date is after to date",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "'from' date must be before or equal to 'to' date",
                        "details": [
                          {
                            "field": "from",
                            "message": "'from' date must be before or equal to 'to' date",
                            "code": "custom"
                          }
                        ]
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1c",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  },
                  "invalidGroupBy": {
                    "summary": "Invalid groupBy value",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Invalid enum value. Expected 'day' | 'week' | 'month'",
                        "details": [
                          {
                            "field": "groupBy",
                            "message": "Invalid enum value. Expected 'day' | 'week' | 'month'",
                            "code": "invalid_enum_value"
                          }
                        ]
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1d",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  },
                  "invalidCursor": {
                    "summary": "Malformed cursor value",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Invalid cursor format. Cursor must be base64 encoded (created_at, id).",
                        "details": []
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1e",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingToken": {
                    "summary": "No authorization token provided",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1f",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  },
                  "expiredToken": {
                    "summary": "JWT token has expired",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "TOKEN_EXPIRED",
                        "message": "Token expired"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1g",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalError": {
                    "summary": "Unexpected server error",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "INTERNAL_SERVER_ERROR",
                        "message": "Internal server error"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t1h",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/usage/sse": {
      "get": {
        "summary": "Stream live usage events",
        "description": "Streams live usage events for the authenticated user over Server-Sent Events. Clients should keep the connection open and process connected and usage events as they arrive.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "SSE stream established successfully",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "connected": {
                    "summary": "Initial connected event sent on stream open",
                    "value": "event: connected\ndata: {\"status\":\"connected\"}\n\n"
                  },
                  "usageEvent": {
                    "summary": "Live usage event pushed to the stream",
                    "value": "event: usage\ndata: {\"id\":\"evt_01hx9r2k3m4n5p6q7r8s9t2a\",\"apiId\":\"api_weather_v1\",\"endpoint\":\"/v1/weather/current\",\"occurredAt\":\"2026-07-01T14:32:00.000Z\",\"revenue\":\"1000000\"}\n\n"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingToken": {
                    "summary": "No authorization token provided",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t2b",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/usage/by-endpoint": {
      "get": {
        "summary": "Top-N endpoints by call volume",
        "description": "Returns the authenticated developer's most-called API endpoints ranked by call volume within the requested time window. Useful for identifying hot endpoints and optimising spend. Defaults to the last 30 days and top 5 endpoints when the corresponding query parameters are omitted.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start of period (ISO-8601). Defaults to 30 days ago.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End of period (ISO-8601). Defaults to now.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of endpoints to return. Must be a positive integer. Defaults to 5.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 5
            }
          },
          {
            "name": "apiId",
            "in": "query",
            "description": "Filter results to a specific API by its ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top endpoints returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "period"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "Endpoints ordered by call count descending. Ties are broken by endpoint path ascending.",
                      "items": {
                        "type": "object",
                        "required": [
                          "endpoint",
                          "calls",
                          "revenue"
                        ],
                        "properties": {
                          "endpoint": {
                            "type": "string",
                            "description": "Endpoint path (e.g. `/v1/weather/current`)."
                          },
                          "calls": {
                            "type": "integer",
                            "description": "Total number of calls to this endpoint in the period."
                          },
                          "revenue": {
                            "type": "string",
                            "description": "Total revenue generated in smallest USDC units (string to avoid precision loss)."
                          }
                        }
                      }
                    },
                    "period": {
                      "type": "object",
                      "required": [
                        "from",
                        "to"
                      ],
                      "properties": {
                        "from": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Effective start of the query period."
                        },
                        "to": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Effective end of the query period."
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "topEndpoints": {
                    "summary": "Two most-called endpoints in the period",
                    "value": {
                      "data": [
                        {
                          "endpoint": "/v1/weather/current",
                          "calls": 142,
                          "revenue": "142000"
                        },
                        {
                          "endpoint": "/v1/weather/forecast",
                          "calls": 87,
                          "revenue": "87000"
                        }
                      ],
                      "period": {
                        "from": "2026-06-01T00:00:00.000Z",
                        "to": "2026-07-01T00:00:00.000Z"
                      }
                    }
                  },
                  "filteredByApi": {
                    "summary": "Top endpoints filtered to a single API",
                    "value": {
                      "data": [
                        {
                          "endpoint": "/v2/geocode",
                          "calls": 310,
                          "revenue": "310000"
                        }
                      ],
                      "period": {
                        "from": "2026-07-01T00:00:00.000Z",
                        "to": "2026-07-27T00:00:00.000Z"
                      }
                    }
                  },
                  "empty": {
                    "summary": "No calls in the requested period",
                    "value": {
                      "data": [],
                      "period": {
                        "from": "2026-01-01T00:00:00.000Z",
                        "to": "2026-01-02T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters (bad date format, invalid limit, `from` after `to`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidDateRange": {
                    "summary": "from is after to",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "from must be before or equal to to"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t3a",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  },
                  "invalidLimit": {
                    "summary": "Non-positive limit value",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "limit must be a positive integer"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t3b",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  },
                  "invalidDate": {
                    "summary": "Malformed date string in from/to parameter",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Invalid \"from\" date"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t3c",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingToken": {
                    "summary": "No authorization token provided",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t3d",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalError": {
                    "summary": "Unexpected server error",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "INTERNAL_SERVER_ERROR",
                        "message": "Internal server error"
                      },
                      "requestId": "req-01hx9r2k3m4n5p6q7r8s9t3e",
                      "timestamp": "2026-07-01T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/usage/anomalies": {
      "get": {
        "summary": "List detected usage anomalies",
        "description": "Returns per-API daily usage anomalies for admin review. Usage events are aggregated to per-API daily call counts over the requested window, then each API's days are scored against that API's own baseline using a z-score test; days whose absolute z-score meets the threshold are flagged as spikes or drops. Requires admin authentication and the admin IP allowlist.",
        "security": [
          {
            "adminApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start of analysis window (ISO-8601). Defaults to 30 days ago.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End of analysis window (ISO-8601). Defaults to now.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "threshold",
            "in": "query",
            "description": "Absolute z-score at/above which a day is flagged.",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 10,
              "default": 3
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of anomalies to return (most severe first).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "apiId",
            "in": "query",
            "description": "Restrict analysis to a single API ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detected anomalies retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "apiId": {
                                "type": "string"
                              },
                              "day": {
                                "type": "string",
                                "example": "2026-03-21"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "spike",
                                  "drop"
                                ]
                              },
                              "calls": {
                                "type": "integer"
                              },
                              "revenue": {
                                "type": "string"
                              },
                              "baselineMean": {
                                "type": "number"
                              },
                              "stdDev": {
                                "type": "number"
                              },
                              "zScore": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "window": {
                              "type": "object",
                              "properties": {
                                "from": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "to": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              }
                            },
                            "threshold": {
                              "type": "number"
                            },
                            "minDataPoints": {
                              "type": "integer"
                            },
                            "seriesAnalyzed": {
                              "type": "integer"
                            },
                            "anomalyCount": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized admin request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden by admin IP allowlist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/usage/{developerId}": {
      "get": {
        "summary": "Inspect a developer usage aggregate",
        "description": "Returns a redacted aggregate snapshot for a developer's live usageStore state. Requires admin authentication and the admin IP allowlist.",
        "security": [
          {
            "adminApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "developerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage aggregate snapshot retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUsageSnapshotResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized admin request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden by admin IP allowlist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Usage aggregate not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/usage/{developerId}/reset": {
      "post": {
        "summary": "Reset a developer usage aggregate",
        "description": "Resets a developer's live usageStore aggregate and writes an audit log with the prior aggregate values. Requires admin authentication and the admin IP allowlist.",
        "security": [
          {
            "adminApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "developerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage aggregate reset successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUsageResetResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized admin request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden by admin IP allowlist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Usage aggregate not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/apis": {
      "get": {
        "summary": "List public APIs",
        "description": "Returns a paginated list of public active APIs, optionally filtered by category or search term. Successful responses include a strong ETag; clients may send If-None-Match for conditional GET (304 when unchanged).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "Strong ETag from a previous listings response. When it matches the current representation, the server returns 304 Not Modified.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved list of public APIs",
            "headers": {
              "ETag": {
                "description": "Strong SHA-256 ETag of the JSON response body",
                "schema": {
                  "type": "string",
                  "example": "\"a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456\""
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApisListResponse"
                },
                "examples": {
                  "activeListings": {
                    "summary": "Active API listings page",
                    "value": {
                      "data": [
                        {
                          "id": 101,
                          "name": "GrantFox Scoring API",
                          "description": "Scores FWC26 grant applications against program rules.",
                          "base_url": "https://api.grantfox.example",
                          "logo_url": "https://cdn.grantfox.example/logo.png",
                          "category": "grants",
                          "status": "active",
                          "developer": {
                            "id": 11,
                            "name": "GrantFox Labs"
                          },
                          "endpoints": [
                            {
                              "id": 501,
                              "api_id": 101,
                              "path": "/applications/{applicationId}/score",
                              "method": "POST",
                              "price_per_call_usdc": "0.2500000",
                              "description": "Score a single grant application.",
                              "created_at": "2026-07-27T09:00:00.000Z",
                              "updated_at": "2026-07-27T09:00:00.000Z"
                            }
                          ]
                        },
                        {
                          "id": 102,
                          "name": "GrantFox Eligibility API",
                          "description": "Validates applicant eligibility before scoring.",
                          "base_url": "https://api.grantfox.example",
                          "logo_url": null,
                          "category": "grants",
                          "status": "active",
                          "developer": {
                            "id": 11,
                            "name": "GrantFox Labs"
                          },
                          "endpoints": [
                            {
                              "id": 502,
                              "api_id": 102,
                              "path": "/applications/{applicationId}/eligibility",
                              "method": "GET",
                              "price_per_call_usdc": "0.0500000",
                              "description": "Return eligibility checks for an application.",
                              "created_at": "2026-07-27T09:05:00.000Z",
                              "updated_at": "2026-07-27T09:05:00.000Z"
                            }
                          ]
                        }
                      ],
                      "meta": {
                        "limit": 20,
                        "hasMore": false
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not Modified — the listings representation matches If-None-Match; response body is empty",
            "headers": {
              "ETag": {
                "description": "Strong ETag of the unchanged representation",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalServerError": {
                    "summary": "Unexpected repository error",
                    "value": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal server error",
                      "requestId": "req-apis-list-500"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Publish a new API",
        "description": "Registers a new API with associated endpoints for the authenticated developer.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiCreateRequest"
              },
              "examples": {
                "publishApi": {
                  "summary": "Publish a grant review API",
                  "value": {
                    "name": "GrantFox Review API",
                    "description": "Automates FWC26 application review workflows.",
                    "base_url": "https://api.grantfox.example",
                    "category": "grants",
                    "endpoints": [
                      {
                        "path": "/applications/{applicationId}/review",
                        "method": "POST",
                        "price_per_call_usdc": "0.3000000",
                        "description": "Run the full review pipeline for one application."
                      },
                      {
                        "path": "/applications/{applicationId}/status",
                        "method": "GET",
                        "price_per_call_usdc": "0.0200000",
                        "description": "Fetch the latest review status."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCreateResponse"
                },
                "examples": {
                  "createdApi": {
                    "summary": "API published successfully",
                    "value": {
                      "id": 301,
                      "developer_id": 11,
                      "name": "GrantFox Review API",
                      "description": "Automates FWC26 application review workflows.",
                      "base_url": "https://api.grantfox.example",
                      "logo_url": null,
                      "category": "grants",
                      "status": "active",
                      "created_at": "2026-07-27T10:00:00.000Z",
                      "updated_at": "2026-07-27T10:00:00.000Z",
                      "endpoints": [
                        {
                          "id": 801,
                          "api_id": 301,
                          "path": "/applications/{applicationId}/review",
                          "method": "POST",
                          "price_per_call_usdc": "0.3000000",
                          "description": "Run the full review pipeline for one application.",
                          "created_at": "2026-07-27T10:00:00.000Z",
                          "updated_at": "2026-07-27T10:00:00.000Z"
                        },
                        {
                          "id": 802,
                          "api_id": 301,
                          "path": "/applications/{applicationId}/status",
                          "method": "GET",
                          "price_per_call_usdc": "0.0200000",
                          "description": "Fetch the latest review status.",
                          "created_at": "2026-07-27T10:00:00.000Z",
                          "updated_at": "2026-07-27T10:00:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload or developer profile not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidPayload": {
                    "summary": "Validation failed",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "Path must start with /",
                      "requestId": "req-apis-create-400",
                      "details": [
                        {
                          "field": "endpoints.0.path",
                          "message": "Path must start with /",
                          "code": "custom"
                        }
                      ]
                    }
                  },
                  "developerProfileMissing": {
                    "summary": "Developer profile missing",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "Developer profile not found. Create a developer profile first.",
                      "requestId": "req-apis-create-dev-missing"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Unauthorized",
                      "requestId": "req-apis-create-401"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalServerError": {
                    "summary": "Unexpected persistence error",
                    "value": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal server error",
                      "requestId": "req-apis-create-500"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/apis/{id}": {
      "get": {
        "summary": "Get API details",
        "description": "Returns the detailed schema and endpoints of an API by its numerical ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiDetailsResponse"
                },
                "examples": {
                  "apiDetails": {
                    "summary": "Detailed API record",
                    "value": {
                      "id": 101,
                      "name": "GrantFox Scoring API",
                      "description": "Scores FWC26 grant applications against program rules.",
                      "base_url": "https://api.grantfox.example",
                      "logo_url": "https://cdn.grantfox.example/logo.png",
                      "category": "grants",
                      "status": "active",
                      "developer": {
                        "id": 11,
                        "name": "GrantFox Labs"
                      },
                      "endpoints": [
                        {
                          "id": 501,
                          "api_id": 101,
                          "path": "/applications/{applicationId}/score",
                          "method": "POST",
                          "price_per_call_usdc": "0.2500000",
                          "description": "Score a single grant application.",
                          "created_at": "2026-07-27T09:00:00.000Z",
                          "updated_at": "2026-07-27T09:00:00.000Z"
                        },
                        {
                          "id": 503,
                          "api_id": 101,
                          "path": "/applications/{applicationId}/score/explain",
                          "method": "GET",
                          "price_per_call_usdc": "0.0400000",
                          "description": "Fetch scoring rationale for the latest run.",
                          "created_at": "2026-07-27T09:10:00.000Z",
                          "updated_at": "2026-07-27T09:10:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidId": {
                    "summary": "Invalid API id",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "id must be a positive integer",
                      "requestId": "req-api-details-400"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "API not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "apiNotFound": {
                    "summary": "API not found",
                    "value": {
                      "code": "NOT_FOUND",
                      "message": "API not found or not active",
                      "requestId": "req-api-details-404"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalServerError": {
                    "summary": "Unexpected lookup error",
                    "value": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal server error",
                      "requestId": "req-api-details-500"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/developers/revenue": {
      "get": {
        "summary": "Retrieve developer revenue and settlements",
        "description": "Returns the authenticated developer's revenue totals, pending settlements, available balance, and a paginated list of settlement transactions.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revenue statistics and settlements retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRevenueResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden (no developer profile)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/exports": {
      "get": {
        "summary": "List export artifacts for GrantFox FWC26 campaign",
        "description": "Returns a paginated list of materialized export artifacts for the authenticated developer. Part of the GrantFox FWC26 (Stellar Wave) campaign. Each export provides a signed download URL for accessing the artifact from object storage.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of export records to return (1-100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "developerId",
            "in": "query",
            "description": "Filter by developer ID (admin-only)",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Filter by export format",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Export artifacts retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "developerId",
                          "format",
                          "exportedAt",
                          "expiresAt",
                          "downloadUrl"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "Unique export record identifier"
                          },
                          "developerId": {
                            "type": "string",
                            "description": "Developer identifier who owns this export"
                          },
                          "format": {
                            "type": "string",
                            "enum": [
                              "csv",
                              "json"
                            ],
                            "description": "Export file format"
                          },
                          "exportedAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO-8601 UTC timestamp when the export was created"
                          },
                          "expiresAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO-8601 UTC timestamp when the export record expires (7 days after creation)"
                          },
                          "downloadUrl": {
                            "type": "string",
                            "format": "uri",
                            "description": "Signed download URL for the export artifact. Expires per EXPORT_SIGNED_URL_TTL_SECONDS (default 900s / 15 minutes)"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "total"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "Requested page size"
                        },
                        "offset": {
                          "type": "integer",
                          "description": "Requested pagination offset"
                        },
                        "total": {
                          "type": "integer",
                          "description": "Total number of export records matching the query"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "developerId": "dev-123",
                      "format": "csv",
                      "exportedAt": "2026-06-01T00:00:00.000Z",
                      "expiresAt": "2026-06-08T00:00:00.000Z",
                      "downloadUrl": "https://s3.example.com/exports/dev-123/2026-06-01.csv?expires=1234567890&signature=abc123"
                    }
                  ],
                  "pagination": {
                    "limit": 20,
                    "offset": 0,
                    "total": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "Authentication required",
                  "requestId": "req-abc123def456"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - no developer profile found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "DEVELOPER_NOT_FOUND",
                  "message": "No developer profile found for this account",
                  "requestId": "req-abc123def456"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/developers/me/keys": {
      "get": {
        "summary": "List developer's own API keys",
        "description": "Returns a paginated list of the authenticated developer's API keys using cursor-based pagination.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of API keys to return per page (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Base64 encoded cursor from a previous response to paginate forward",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API keys retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKeysResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters or cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden (no developer profile)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/developers/me/usage/summary": {
      "get": {
        "summary": "Retrieve developer usage summary",
        "description": "Returns aggregate usage metrics, per-API breakdown, and time-series buckets for the authenticated developer.",
        "tags": [
          "Developers"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start date for summary window (ISO 8601 string)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End date for summary window (ISO 8601 string)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "groupBy",
            "in": "query",
            "description": "Aggregation bucket period ('day', 'week', 'month')",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ],
              "default": "day"
            }
          },
          {
            "name": "apiId",
            "in": "query",
            "description": "Filter by specific API ID belonging to the developer",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Developer usage summary retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperUsageSummaryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters or date range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden (no developer profile or API not owned by developer)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/apis/{id}/endpoints/bulk": {
      "post": {
        "summary": "Bulk register endpoints for an API",
        "description": "Registers multiple endpoints atomically for the specified API. All endpoints are inserted in a single transaction; if any endpoint is invalid the entire batch is rolled back. Authenticated developer must own the API.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Numerical ID of the API"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkEndpointRegistrationRequest"
              },
              "examples": {
                "bulkRegisterEndpoints": {
                  "summary": "Add two endpoints to an API",
                  "value": {
                    "endpoints": [
                      {
                        "path": "/applications/{applicationId}/decision",
                        "method": "POST",
                        "price_per_call_usdc": "0.1800000",
                        "description": "Create a funding decision recommendation."
                      },
                      {
                        "path": "/applications/{applicationId}/timeline",
                        "method": "GET",
                        "price_per_call_usdc": "0.0150000",
                        "description": "Return review timeline milestones."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Endpoints registered successfully — per-row details returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkEndpointRegistrationResponse"
                },
                "examples": {
                  "createdEndpoints": {
                    "summary": "Endpoints added successfully",
                    "value": {
                      "endpoints": [
                        {
                          "id": 901,
                          "api_id": 301,
                          "path": "/applications/{applicationId}/decision",
                          "method": "POST",
                          "price_per_call_usdc": "0.1800000",
                          "description": "Create a funding decision recommendation."
                        },
                        {
                          "id": 902,
                          "api_id": 301,
                          "path": "/applications/{applicationId}/timeline",
                          "method": "GET",
                          "price_per_call_usdc": "0.0150000",
                          "description": "Return review timeline milestones."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — invalid endpoint data, empty array, or too many endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidEndpoint": {
                    "summary": "Invalid endpoint payload",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "Price per call must be a non-negative decimal string",
                      "requestId": "req-bulk-endpoints-400",
                      "details": [
                        {
                          "field": "endpoints.0.price_per_call_usdc",
                          "message": "Price per call must be a non-negative decimal string",
                          "code": "custom"
                        }
                      ]
                    }
                  },
                  "tooManyEndpoints": {
                    "summary": "Too many endpoints submitted",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "Cannot register more than 50 endpoints at once",
                      "requestId": "req-bulk-endpoints-too-many"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Unauthorized",
                      "requestId": "req-bulk-endpoints-401"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "API not found or does not belong to the developer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "apiNotFound": {
                    "summary": "Owned API not found",
                    "value": {
                      "code": "NOT_FOUND",
                      "message": "API not found",
                      "requestId": "req-bulk-endpoints-404"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "internalServerError": {
                    "summary": "Unexpected persistence error",
                    "value": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal server error",
                      "requestId": "req-bulk-endpoints-500"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/marketplace/plugins": {
      "get": {
        "summary": "List all plugins",
        "description": "Returns all registered community plugins from the marketplace.",
        "responses": {
          "200": {
            "description": "Plugin list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plugins",
                    "total"
                  ],
                  "properties": {
                    "plugins": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PluginRecord"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Register a new plugin",
        "description": "Registers a new community plugin manifest. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PluginManifest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plugin registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginRecord"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Plugin already registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/marketplace/plugins/{id}": {
      "get": {
        "summary": "Get a plugin by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plugin found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginRecord"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove a plugin from the registry",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Plugin removed"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/marketplace/plugins/{id}/install": {
      "post": {
        "summary": "Install a plugin",
        "description": "Marks a plugin as installed and fires the install hook. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plugin installed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plugin"
                  ],
                  "properties": {
                    "plugin": {
                      "$ref": "#/components/schemas/PluginRecord"
                    },
                    "hook": {
                      "nullable": true,
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean"
                        },
                        "hook": {
                          "type": "string"
                        },
                        "pluginId": {
                          "type": "string"
                        },
                        "sandboxed": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Already installed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Uninstall a plugin",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plugin uninstalled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginRecord"
                }
              }
            }
          },
          "400": {
            "description": "Not installed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/disputes": {
      "post": {
        "summary": "Open a dispute",
        "description": "Developer opens a dispute against a billing charge (usage event). One open dispute is allowed per usage_event_id.",
        "tags": [
          "Billing",
          "Disputes"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OpenDisputeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dispute opened successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dispute"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Unauthorized"
          },
          "409": {
            "description": "Dispute already exists for this usage_event_id"
          }
        }
      },
      "get": {
        "summary": "List own disputes",
        "description": "Returns all disputes opened by the authenticated developer.",
        "tags": [
          "Billing",
          "Disputes"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of disputes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "disputes",
                    "total"
                  ],
                  "properties": {
                    "disputes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Dispute"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/billing/disputes/{id}": {
      "get": {
        "summary": "Get own dispute with audit trail",
        "description": "Returns a single dispute and its full audit event trail. Only the dispute owner may access it.",
        "tags": [
          "Billing",
          "Disputes"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dispute with events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dispute",
                    "events"
                  ],
                  "properties": {
                    "dispute": {
                      "$ref": "#/components/schemas/Dispute"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DisputeEvent"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden: dispute belongs to another user"
          },
          "404": {
            "description": "Dispute not found"
          }
        }
      }
    },
    "/api/billing/disputes/{id}/resolve": {
      "post": {
        "summary": "Resolve a dispute (admin)",
        "description": "Admin resolves an open dispute as REFUNDED or UPHELD. Requires admin authentication.",
        "tags": [
          "Billing",
          "Disputes"
        ],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveDisputeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dispute resolved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dispute"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Admin authentication required"
          },
          "404": {
            "description": "Dispute not found"
          },
          "409": {
            "description": "Dispute already resolved"
          }
        }
      }
    },
    "/api/billing/disputes/admin/all": {
      "get": {
        "summary": "List all disputes (admin)",
        "description": "Admin endpoint to list every dispute in the system.",
        "tags": [
          "Billing",
          "Disputes"
        ],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "All disputes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "disputes",
                    "total"
                  ],
                  "properties": {
                    "disputes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Dispute"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication required"
          }
        }
      }
    },
    "/api/quota/requests": {
      "post": {
        "summary": "Submit a quota request",
        "description": "Creates a new quota increase request for the authenticated developer. The request remains pending until an admin resolves it.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuotaRequestCreate"
              },
              "examples": {
                "createRequest": {
                  "summary": "Quota increase request",
                  "value": {
                    "requested_tier": "pro",
                    "reason": "We need a higher monthly call cap for our beta launch.",
                    "requested_overrides": {
                      "monthly_call_limit": 250000,
                      "rate_limit_max_requests": 1000
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quota request created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QuotaRequest"
                    }
                  }
                },
                "examples": {
                  "createdRequest": {
                    "summary": "Created quota request",
                    "value": {
                      "data": {
                        "id": "8dbc1b8b-5fe5-4e2f-8ece-9f0d7f9e5743",
                        "developerId": "dev_123",
                        "requestedTier": "pro",
                        "reason": "We need a higher monthly call cap for our beta launch.",
                        "requestedOverrides": {
                          "monthlyCallLimit": 250000,
                          "rateLimitMaxRequests": 1000
                        },
                        "status": "pending",
                        "createdAt": "2026-07-26T12:34:56.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "validationError": {
                    "summary": "Validation error",
                    "value": {
                      "code": "VALIDATION_ERROR",
                      "message": "Request validation failed",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Authentication required",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unprocessable": {
                    "summary": "Unprocessable entity",
                    "value": {
                      "code": "UNPROCESSABLE_ENTITY",
                      "message": "Request validation failed",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List quota requests",
        "description": "Lists the authenticated developer's own quota requests. An optional status query parameter filters the results.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Optional status filter",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of quota requests",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QuotaRequest"
                      }
                    }
                  }
                },
                "examples": {
                  "listSuccess": {
                    "summary": "List of requests",
                    "value": {
                      "data": [
                        {
                          "id": "8dbc1b8b-5fe5-4e2f-8ece-9f0d7f9e5743",
                          "developerId": "dev_123",
                          "requestedTier": "pro",
                          "reason": "We need a higher monthly call cap for our beta launch.",
                          "requestedOverrides": {
                            "monthlyCallLimit": 250000,
                            "rateLimitMaxRequests": 1000
                          },
                          "status": "pending",
                          "createdAt": "2026-07-26T12:34:56.000Z"
                        },
                        {
                          "id": "c51082b2-9f67-4f57-8d7e-0784f09e5ea6",
                          "developerId": "dev_123",
                          "requestedTier": "enterprise",
                          "reason": "We are onboarding a larger enterprise customer base.",
                          "status": "approved",
                          "adminNotes": "Approved for the next billing cycle.",
                          "resolvedBy": "admin_42",
                          "resolvedAt": "2026-07-27T09:00:00.000Z",
                          "createdAt": "2026-07-25T10:15:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid status filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidStatus": {
                    "summary": "Invalid status value",
                    "value": {
                      "code": "BAD_REQUEST",
                      "message": "status must be one of: pending, approved, rejected",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Authentication required",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quota/requests/{id}": {
      "get": {
        "summary": "Get a quota request",
        "description": "Returns a single quota request by ID for the authenticated developer. Requests belonging to another developer appear as not found.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Quota request UUID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quota request retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QuotaRequest"
                    }
                  }
                },
                "examples": {
                  "singleRequest": {
                    "summary": "Single quota request",
                    "value": {
                      "data": {
                        "id": "8dbc1b8b-5fe5-4e2f-8ece-9f0d7f9e5743",
                        "developerId": "dev_123",
                        "requestedTier": "pro",
                        "reason": "We need a higher monthly call cap for our beta launch.",
                        "requestedOverrides": {
                          "monthlyCallLimit": 250000,
                          "rateLimitMaxRequests": 1000
                        },
                        "status": "pending",
                        "createdAt": "2026-07-26T12:34:56.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "code": "UNAUTHORIZED",
                      "message": "Authentication required",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Quota request not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "summary": "Quota request missing or inaccessible",
                    "value": {
                      "code": "NOT_FOUND",
                      "message": "Quota request not found",
                      "requestId": "req-abc123"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/errors": {
      "get": {
        "summary": "List error definitions",
        "description": "Returns all registered error definitions. Read-only; does not require authentication and is not audited.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Error definitions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorsListResponse"
                },
                "examples": {
                  "withRecords": {
                    "summary": "Store contains registered error definitions",
                    "value": {
                      "success": true,
                      "data": {
                        "errors": [
                          {
                            "id": "1",
                            "code": "ERR_INSUFFICIENT_CREDITS",
                            "message": "Developer account has insufficient credits",
                            "statusCode": 402,
                            "description": "Returned when a billing deduction would take the balance below zero.",
                            "createdAt": "2026-07-27T09:00:00.000Z",
                            "updatedAt": "2026-07-27T09:00:00.000Z"
                          }
                        ]
                      },
                      "requestId": "req-errors-list-1",
                      "timestamp": "2026-07-27T09:00:00.000Z"
                    }
                  },
                  "empty": {
                    "summary": "No error definitions registered yet",
                    "value": {
                      "success": true,
                      "data": {
                        "errors": []
                      },
                      "requestId": "req-errors-list-2",
                      "timestamp": "2026-07-27T09:05:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an error definition",
        "description": "Registers a new error definition. Requires authentication; the mutation is recorded in the audit log.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorCreateRequest"
              },
              "examples": {
                "createErrorDefinition": {
                  "summary": "Register a new billing error code",
                  "value": {
                    "code": "ERR_INSUFFICIENT_CREDITS",
                    "message": "Developer account has insufficient credits",
                    "statusCode": 402,
                    "description": "Returned when a billing deduction would take the balance below zero."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Error definition created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRecordResponse"
                },
                "examples": {
                  "created": {
                    "summary": "Newly created error definition",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "1",
                        "code": "ERR_INSUFFICIENT_CREDITS",
                        "message": "Developer account has insufficient credits",
                        "statusCode": 402,
                        "description": "Returned when a billing deduction would take the balance below zero.",
                        "createdAt": "2026-07-27T09:00:00.000Z",
                        "updatedAt": "2026-07-27T09:00:00.000Z"
                      },
                      "requestId": "req-errors-create-1",
                      "timestamp": "2026-07-27T09:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "validationFailed": {
                    "summary": "Missing required field",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Validation failed",
                        "details": [
                          {
                            "field": "code",
                            "message": "Required",
                            "code": "invalid_type"
                          }
                        ]
                      },
                      "requestId": "req-errors-create-400",
                      "timestamp": "2026-07-27T09:01:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-errors-create-401",
                      "timestamp": "2026-07-27T09:02:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/errors/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Error definition ID",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Get an error definition by ID",
        "description": "Read-only; does not require authentication and is not audited.",
        "responses": {
          "200": {
            "description": "Error definition retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRecordResponse"
                },
                "examples": {
                  "found": {
                    "summary": "Existing error definition",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "1",
                        "code": "ERR_INSUFFICIENT_CREDITS",
                        "message": "Developer account has insufficient credits",
                        "statusCode": 402,
                        "description": "Returned when a billing deduction would take the balance below zero.",
                        "createdAt": "2026-07-27T09:00:00.000Z",
                        "updatedAt": "2026-07-27T09:00:00.000Z"
                      },
                      "requestId": "req-errors-get-1",
                      "timestamp": "2026-07-27T09:03:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error definition not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No error definition with the given ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Error definition 999 not found"
                      },
                      "requestId": "req-errors-get-404",
                      "timestamp": "2026-07-27T09:04:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Replace an error definition",
        "description": "Full update of an existing error definition. Requires authentication; the mutation is recorded in the audit log.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorUpdateRequest"
              },
              "examples": {
                "replaceErrorDefinition": {
                  "summary": "Update the message and status code",
                  "value": {
                    "code": "ERR_INSUFFICIENT_CREDITS",
                    "message": "Account balance is below the required minimum",
                    "statusCode": 402,
                    "description": "Returned when a billing deduction would take the balance below zero."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Error definition updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRecordResponse"
                },
                "examples": {
                  "updated": {
                    "summary": "Updated error definition",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "1",
                        "code": "ERR_INSUFFICIENT_CREDITS",
                        "message": "Account balance is below the required minimum",
                        "statusCode": 402,
                        "description": "Returned when a billing deduction would take the balance below zero.",
                        "createdAt": "2026-07-27T09:00:00.000Z",
                        "updatedAt": "2026-07-27T09:06:00.000Z"
                      },
                      "requestId": "req-errors-put-1",
                      "timestamp": "2026-07-27T09:06:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "emptyUpdate": {
                    "summary": "No fields provided",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "At least one field must be provided for update"
                      },
                      "requestId": "req-errors-put-400",
                      "timestamp": "2026-07-27T09:07:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-errors-put-401",
                      "timestamp": "2026-07-27T09:08:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error definition not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No error definition with the given ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Error definition 999 not found"
                      },
                      "requestId": "req-errors-put-404",
                      "timestamp": "2026-07-27T09:09:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Partially update an error definition",
        "description": "Partial update of an existing error definition. Requires authentication; the mutation is recorded in the audit log.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorUpdateRequest"
              },
              "examples": {
                "patchMessage": {
                  "summary": "Update just the message",
                  "value": {
                    "message": "Account balance is below the required minimum"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Error definition updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRecordResponse"
                },
                "examples": {
                  "updated": {
                    "summary": "Updated error definition",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "1",
                        "code": "ERR_INSUFFICIENT_CREDITS",
                        "message": "Account balance is below the required minimum",
                        "statusCode": 402,
                        "description": "Returned when a billing deduction would take the balance below zero.",
                        "createdAt": "2026-07-27T09:00:00.000Z",
                        "updatedAt": "2026-07-27T09:10:00.000Z"
                      },
                      "requestId": "req-errors-patch-1",
                      "timestamp": "2026-07-27T09:10:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "emptyUpdate": {
                    "summary": "No fields provided",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "At least one field must be provided for update"
                      },
                      "requestId": "req-errors-patch-400",
                      "timestamp": "2026-07-27T09:11:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-errors-patch-401",
                      "timestamp": "2026-07-27T09:12:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error definition not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No error definition with the given ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Error definition 999 not found"
                      },
                      "requestId": "req-errors-patch-404",
                      "timestamp": "2026-07-27T09:13:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete an error definition",
        "description": "Requires authentication; the mutation is recorded in the audit log. Returns no content on success.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "Error definition deleted"
          },
          "401": {
            "description": "Authentication is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-errors-delete-401",
                      "timestamp": "2026-07-27T09:14:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error definition not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No error definition with the given ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Error definition 999 not found"
                      },
                      "requestId": "req-errors-delete-404",
                      "timestamp": "2026-07-27T09:15:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/spike": {
      "get": {
        "summary": "Run the spike timeout probe",
        "description": "Exercises timeout handling by delaying for the requested duration. No request body is required.\n",
        "parameters": [
          {
            "name": "delay",
            "in": "query",
            "required": false,
            "description": "Delay in milliseconds before responding.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 2000
            },
            "examples": {
              "completesBeforeTimeout": {
                "summary": "Complete before the default timeout",
                "value": 100
              },
              "exceedsDefaultTimeout": {
                "summary": "Trigger the default timeout",
                "value": 1200
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Spike probe completed before the timeout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpikeRunResponse"
                },
                "examples": {
                  "completed": {
                    "summary": "Delay completed successfully",
                    "value": {
                      "success": true,
                      "message": "Spike completed successfully",
                      "delay": 100,
                      "elapsed": 100
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Spike probe exceeded the configured timeout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "timedOut": {
                    "summary": "Request timed out",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "GATEWAY_TIMEOUT",
                        "message": "Request timeout exceeded"
                      },
                      "requestId": "req-spike-timeout-1",
                      "timestamp": "2026-07-29T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a spike record",
        "description": "Creates an in-memory spike record and records the mutation in the audit trail.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpikeCreateRequest"
              },
              "examples": {
                "createHighSeverityRecord": {
                  "summary": "Create a high severity spike record",
                  "value": {
                    "label": "Checkout latency spike",
                    "severity": "high"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Spike record created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpikeRecord"
                },
                "examples": {
                  "created": {
                    "summary": "Newly created spike record",
                    "value": {
                      "id": "1",
                      "label": "Checkout latency spike",
                      "severity": "high",
                      "createdAt": "2026-07-29T10:00:00.000Z",
                      "updatedAt": "2026-07-29T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "missingLabel": {
                    "summary": "Missing required label",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "label is required and must be a non-empty string"
                      },
                      "requestId": "req-spike-create-400",
                      "timestamp": "2026-07-29T10:01:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Audit service is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "auditUnavailable": {
                    "summary": "Audit circuit breaker is open",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "SERVICE_UNAVAILABLE",
                        "message": "Audit service temporarily unavailable"
                      },
                      "requestId": "req-spike-create-503",
                      "timestamp": "2026-07-29T10:02:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/spike/records": {
      "get": {
        "summary": "List spike records",
        "description": "Returns the current in-memory spike records.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Spike records retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpikeRecordsResponse"
                },
                "examples": {
                  "withRecords": {
                    "summary": "Store contains spike records",
                    "value": {
                      "records": [
                        {
                          "id": "1",
                          "label": "Checkout latency spike",
                          "severity": "high",
                          "createdAt": "2026-07-29T10:00:00.000Z",
                          "updatedAt": "2026-07-29T10:00:00.000Z"
                        }
                      ]
                    }
                  },
                  "empty": {
                    "summary": "No spike records exist yet",
                    "value": {
                      "records": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/spike/{id}": {
      "put": {
        "summary": "Update a spike record",
        "description": "Updates the label and/or severity for an existing spike record and records the mutation in the audit trail.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Spike record identifier.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "existingRecord": {
                "summary": "Existing spike record",
                "value": "1"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpikeUpdateRequest"
              },
              "examples": {
                "updateSeverity": {
                  "summary": "Escalate the spike severity",
                  "value": {
                    "label": "Checkout latency spike escalated",
                    "severity": "critical"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Spike record updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpikeRecord"
                },
                "examples": {
                  "updated": {
                    "summary": "Updated spike record",
                    "value": {
                      "id": "1",
                      "label": "Checkout latency spike escalated",
                      "severity": "critical",
                      "createdAt": "2026-07-29T10:00:00.000Z",
                      "updatedAt": "2026-07-29T10:05:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "invalidSeverity": {
                    "summary": "Severity is outside the allowed set",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Invalid option"
                      },
                      "requestId": "req-spike-update-400",
                      "timestamp": "2026-07-29T10:06:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Spike record was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No record exists for the supplied ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Spike record 999 not found"
                      },
                      "requestId": "req-spike-update-404",
                      "timestamp": "2026-07-29T10:07:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Audit service is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "auditUnavailable": {
                    "summary": "Audit circuit breaker is open",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "SERVICE_UNAVAILABLE",
                        "message": "Audit service temporarily unavailable"
                      },
                      "requestId": "req-spike-update-503",
                      "timestamp": "2026-07-29T10:08:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a spike record",
        "description": "Deletes an existing spike record and records the mutation in the audit trail. Returns no content on success.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Spike record identifier.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "existingRecord": {
                "summary": "Existing spike record",
                "value": "1"
              }
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Spike record deleted."
          },
          "404": {
            "description": "Spike record was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "No record exists for the supplied ID",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "Spike record 999 not found"
                      },
                      "requestId": "req-spike-delete-404",
                      "timestamp": "2026-07-29T10:09:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Audit service is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "auditUnavailable": {
                    "summary": "Audit circuit breaker is open",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "SERVICE_UNAVAILABLE",
                        "message": "Audit service temporarily unavailable"
                      },
                      "requestId": "req-spike-delete-503",
                      "timestamp": "2026-07-29T10:10:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/tenants": {
      "get": {
        "summary": "List tenants",
        "description": "Returns all tenants visible to the authenticated user. Responses are ETag-stamped so clients can use conditional GET (If-None-Match) to avoid redundant transfers.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "x-user-id",
            "in": "header",
            "required": true,
            "description": "Authenticated user identifier (set by auth middleware).",
            "schema": {
              "type": "string"
            },
            "examples": {
              "developer": {
                "summary": "Authenticated developer",
                "value": "dev-1"
              }
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "Strong ETag from a prior response. Returns 304 if the tenant list has not changed.\n",
            "schema": {
              "type": "string"
            },
            "examples": {
              "etag": {
                "summary": "Strong ETag from prior response",
                "value": "\"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\""
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant list retrieved successfully.",
            "headers": {
              "ETag": {
                "description": "Strong ETag of the current tenant list payload.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantListResponse"
                },
                "examples": {
                  "withTenants": {
                    "summary": "Two tenants returned",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "ten_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                          "name": "GrantFox Ops",
                          "slug": "grantfox-ops",
                          "contactEmail": "ops@grantfox.test",
                          "plan": "growth",
                          "metadata": {
                            "campaign": "fwc26"
                          },
                          "createdBy": "dev-1",
                          "createdAt": "2026-07-28T00:00:00.000Z",
                          "updatedAt": "2026-07-28T00:00:00.000Z"
                        },
                        {
                          "id": "ten_b2c3d4e5-f6a7-8901-bcde-f12345678901",
                          "name": "GrantFox Stadium",
                          "slug": "grantfox-stadium",
                          "plan": "enterprise",
                          "createdBy": "dev-1",
                          "createdAt": "2026-07-28T00:00:00.000Z",
                          "updatedAt": "2026-07-28T00:00:00.000Z"
                        }
                      ],
                      "requestId": "req-tenants-list-1",
                      "timestamp": "2026-07-28T10:00:00.000Z"
                    }
                  },
                  "empty": {
                    "summary": "No tenants exist yet",
                    "value": {
                      "success": true,
                      "data": [],
                      "requestId": "req-tenants-list-2",
                      "timestamp": "2026-07-28T10:01:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Tenant list has not changed since the ETag supplied in If-None-Match.\n"
          },
          "401": {
            "description": "Authentication is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-tenants-list-401",
                      "timestamp": "2026-07-28T10:02:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a tenant",
        "description": "Creates a new tenant. The request body is Zod-validated at the route boundary; unrecognised keys are rejected with a structured 400 error envelope so clients receive per-field details without any internal information leaking.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantCreateRequest"
              },
              "examples": {
                "createFull": {
                  "summary": "Full tenant payload with optional fields",
                  "value": {
                    "name": "GrantFox Ops",
                    "slug": "grantfox-ops",
                    "contactEmail": "ops@grantfox.test",
                    "plan": "growth",
                    "metadata": {
                      "campaign": "fwc26",
                      "priority": 1,
                      "active": true
                    }
                  }
                },
                "createMinimal": {
                  "summary": "Minimal tenant — only name is required",
                  "value": {
                    "name": "GrantFox Stadium"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tenant created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantResponse"
                },
                "examples": {
                  "created": {
                    "summary": "Newly created tenant",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "ten_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "name": "GrantFox Ops",
                        "slug": "grantfox-ops",
                        "contactEmail": "ops@grantfox.test",
                        "plan": "growth",
                        "metadata": {
                          "campaign": "fwc26",
                          "priority": 1,
                          "active": true
                        },
                        "createdBy": "dev-1",
                        "createdAt": "2026-07-28T10:00:00.000Z",
                        "updatedAt": "2026-07-28T10:00:00.000Z"
                      },
                      "requestId": "req-tenants-create-1",
                      "timestamp": "2026-07-28T10:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed Zod validation. The error envelope includes a per-field `details` array so clients can surface precise messages without any server internals leaking.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "missingName": {
                    "summary": "Required field missing",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body.name",
                            "message": "name is required",
                            "code": "INVALID_TYPE"
                          }
                        ]
                      },
                      "requestId": "req-tenants-create-400-name",
                      "timestamp": "2026-07-28T10:01:00.000Z"
                    }
                  },
                  "invalidEmail": {
                    "summary": "Invalid contactEmail format",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body.contactEmail",
                            "message": "contactEmail must be a valid email address",
                            "code": "INVALID_STRING"
                          }
                        ]
                      },
                      "requestId": "req-tenants-create-400-email",
                      "timestamp": "2026-07-28T10:02:00.000Z"
                    }
                  },
                  "unknownKey": {
                    "summary": "Unrecognised key rejected by strict schema",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body",
                            "message": "Unrecognized key(s) in object: 'unsafeRole'",
                            "code": "UNRECOGNIZED_KEYS"
                          }
                        ]
                      },
                      "requestId": "req-tenants-create-400-unknown",
                      "timestamp": "2026-07-28T10:03:00.000Z"
                    }
                  },
                  "invalidPlan": {
                    "summary": "Plan value outside the allowed enum",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body.plan",
                            "message": "Invalid option: expected one of 'starter' | 'growth' | 'enterprise'",
                            "code": "INVALID_ENUM_VALUE"
                          }
                        ]
                      },
                      "requestId": "req-tenants-create-400-plan",
                      "timestamp": "2026-07-28T10:04:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-tenants-create-401",
                      "timestamp": "2026-07-28T10:05:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/tenants/{tenantId}": {
      "patch": {
        "summary": "Update a tenant",
        "description": "Partially updates an existing tenant. Both the route parameter and the request body are Zod-validated; all validation errors are collected in a single pass and returned together in the structured 400 envelope so the client can fix all issues in one round-trip.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "description": "Tenant identifier — 3–64 characters, letters/numbers/underscores/hyphens.\n",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,63}$"
            },
            "examples": {
              "valid": {
                "summary": "Valid tenant ID",
                "value": "tenant_123"
              },
              "tooShort": {
                "summary": "ID too short — triggers 400",
                "value": "no"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantUpdateRequest"
              },
              "examples": {
                "updatePlan": {
                  "summary": "Upgrade the plan",
                  "value": {
                    "plan": "enterprise"
                  }
                },
                "updateContactEmail": {
                  "summary": "Update contact email only",
                  "value": {
                    "contactEmail": "stadium@grantfox.test"
                  }
                },
                "updateMultiple": {
                  "summary": "Update name, plan, and metadata together",
                  "value": {
                    "name": "GrantFox Stadium Ops",
                    "plan": "enterprise",
                    "metadata": {
                      "campaign": "fwc26-final"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tenant updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantResponse"
                },
                "examples": {
                  "updated": {
                    "summary": "Updated tenant record",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "tenant_123",
                        "name": "GrantFox Stadium Ops",
                        "slug": "grantfox-stadium",
                        "contactEmail": "stadium@grantfox.test",
                        "plan": "enterprise",
                        "metadata": {
                          "campaign": "fwc26-final"
                        },
                        "createdBy": "dev-1",
                        "createdAt": "2026-07-28T00:00:00.000Z",
                        "updatedAt": "2026-07-28T11:00:00.000Z"
                      },
                      "requestId": "req-tenants-update-1",
                      "timestamp": "2026-07-28T11:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Route parameter or body failed Zod validation. All errors are collected in one pass and returned in the `details` array.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "invalidParamAndEmptyBody": {
                    "summary": "Invalid tenantId param and empty body collected together",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body",
                            "message": "At least one tenant field must be provided",
                            "code": "CUSTOM"
                          },
                          {
                            "field": "params.tenantId",
                            "message": "tenantId must be 3-64 characters using letters, numbers, underscores, or hyphens",
                            "code": "INVALID_STRING"
                          }
                        ]
                      },
                      "requestId": "req-tenants-update-400",
                      "timestamp": "2026-07-28T11:01:00.000Z"
                    }
                  },
                  "unknownKey": {
                    "summary": "Unrecognised key in update body",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Request validation failed",
                        "details": [
                          {
                            "field": "body",
                            "message": "Unrecognized key(s) in object: 'slug'",
                            "code": "UNRECOGNIZED_KEYS"
                          }
                        ]
                      },
                      "requestId": "req-tenants-update-400-key",
                      "timestamp": "2026-07-28T11:02:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Missing or invalid authentication",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Unauthorized"
                      },
                      "requestId": "req-tenants-update-401",
                      "timestamp": "2026-07-28T11:03:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks": {
      "post": {
        "summary": "Register a webhook",
        "description": "Registers a new webhook endpoint for a developer. The `events` array must be non-empty and contain only supported event types. The optional `secret` is used for HMAC-SHA256 signing; if omitted the server generates one. The optional `retryPolicy` constrains reattempt behaviour (0–10 retries, 100–60 000 ms base delay).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRegisterRequest"
              },
              "examples": {
                "registerFull": {
                  "summary": "Register with all optional fields",
                  "value": {
                    "developerId": "dev-123",
                    "url": "https://hooks.example.com/callora",
                    "events": [
                      "new_api_call",
                      "low_balance_alert"
                    ],
                    "secret": "s3cr3t-hmac-key",
                    "retryPolicy": {
                      "maxRetries": 3,
                      "baseDelayMs": 1000
                    }
                  }
                },
                "registerMinimal": {
                  "summary": "Register with required fields only",
                  "value": {
                    "developerId": "dev-456",
                    "url": "https://hooks.example.com/minimal",
                    "events": [
                      "settlement_completed"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook registered successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookRegisterResponse"
                },
                "examples": {
                  "registered": {
                    "summary": "Registration confirmed",
                    "value": {
                      "message": "Webhook registered successfully.",
                      "developerId": "dev-123",
                      "url": "https://hooks.example.com/callora",
                      "events": [
                        "new_api_call",
                        "low_balance_alert"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "missingFields": {
                    "summary": "developerId, url, or events missing",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "developerId, url, and a non-empty events array are required."
                      },
                      "requestId": "req-webhook-post-400-missing",
                      "timestamp": "2026-07-27T09:15:00.000Z"
                    }
                  },
                  "invalidEventTypes": {
                    "summary": "Event type not in the supported set",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Invalid event types: invalid_event. Valid: new_api_call, settlement_completed, low_balance_alert"
                      },
                      "requestId": "req-webhook-post-400-events",
                      "timestamp": "2026-07-27T09:16:00.000Z"
                    }
                  },
                  "invalidUrl": {
                    "summary": "URL failed reachability validation",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "URL is not reachable or does not return 2xx"
                      },
                      "requestId": "req-webhook-post-400-url",
                      "timestamp": "2026-07-27T09:17:00.000Z"
                    }
                  },
                  "invalidRetryPolicy": {
                    "summary": "Retry policy values out of range",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "retryPolicy.maxRetries must be between 0 and 10"
                      },
                      "requestId": "req-webhook-post-400-retry",
                      "timestamp": "2026-07-27T09:18:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks/{developerId}": {
      "parameters": [
        {
          "name": "developerId",
          "in": "path",
          "required": true,
          "description": "Developer identifier — 3–128 characters, letters/numbers/underscores/hyphens.\n",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$"
          },
          "examples": {
            "valid": {
              "summary": "Valid developer ID",
              "value": "dev-123"
            }
          }
        }
      ],
      "get": {
        "summary": "Get webhook configuration",
        "description": "Returns the webhook configuration for the given developer. Signing secrets are never returned; the secret fields are omitted from the response.\n",
        "responses": {
          "200": {
            "description": "Webhook configuration returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookConfig"
                },
                "examples": {
                  "found": {
                    "summary": "Webhook configuration with retry policy",
                    "value": {
                      "developerId": "dev-123",
                      "url": "https://hooks.example.com/callora",
                      "events": [
                        "new_api_call",
                        "low_balance_alert"
                      ],
                      "retryPolicy": {
                        "maxRetries": 3,
                        "baseDelayMs": 1000
                      },
                      "createdAt": "2026-07-27T09:00:00.000Z"
                    }
                  },
                  "foundNoRetryPolicy": {
                    "summary": "Webhook configuration without a custom retry policy",
                    "value": {
                      "developerId": "dev-456",
                      "url": "https://hooks.example.com/minimal",
                      "events": [
                        "settlement_completed"
                      ],
                      "createdAt": "2026-07-27T09:05:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No webhook registered for this developer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "Developer has no registered webhook",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "No webhook registered for this developer."
                      },
                      "requestId": "req-webhook-get-404",
                      "timestamp": "2026-07-27T09:06:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove webhook",
        "description": "Removes the webhook configuration for the given developer. The webhook will no longer receive events after deletion.\n",
        "responses": {
          "200": {
            "description": "Webhook removed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeleteResponse"
                },
                "examples": {
                  "removed": {
                    "summary": "Webhook deleted",
                    "value": {
                      "message": "Webhook removed."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks/{developerId}/rotate-secret": {
      "post": {
        "summary": "Rotate webhook signing secret",
        "description": "Rotates the HMAC-SHA256 signing secret for the developer's webhook. The previous secret remains valid for a configurable grace period (WEBHOOK_SECRET_ROTATION_GRACE_MS) so consumers can transition without delivery gaps. The new secret is returned once and never again — store it immediately.\n",
        "parameters": [
          {
            "name": "developerId",
            "in": "path",
            "required": true,
            "description": "Developer identifier.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$"
            },
            "examples": {
              "valid": {
                "summary": "Valid developer ID",
                "value": "dev-123"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Secret rotated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookRotateSecretResponse"
                },
                "examples": {
                  "rotated": {
                    "summary": "New secret and grace-period expiry returned",
                    "value": {
                      "message": "Webhook secret rotated successfully.",
                      "developerId": "dev-123",
                      "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
                      "previous_expires_at": "2026-07-27T10:15:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No webhook registered for this developer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "Developer has no registered webhook",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "No webhook registered for this developer."
                      },
                      "requestId": "req-webhook-rotate-404",
                      "timestamp": "2026-07-27T09:20:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks/{developerId}/retry-policy": {
      "patch": {
        "summary": "Update webhook retry policy",
        "description": "Replaces the retry policy for the developer's webhook subscription. Only `retryPolicy` is updated; all other settings remain unchanged. At least one of `maxRetries` or `baseDelayMs` must be provided.\n",
        "parameters": [
          {
            "name": "developerId",
            "in": "path",
            "required": true,
            "description": "Developer identifier.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$"
            },
            "examples": {
              "valid": {
                "summary": "Valid developer ID",
                "value": "dev-123"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRetryPolicyUpdateRequest"
              },
              "examples": {
                "setCustomPolicy": {
                  "summary": "Apply a custom retry policy",
                  "value": {
                    "retryPolicy": {
                      "maxRetries": 5,
                      "baseDelayMs": 2000
                    }
                  }
                },
                "setMaxRetriesOnly": {
                  "summary": "Change only the retry count",
                  "value": {
                    "retryPolicy": {
                      "maxRetries": 10
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Retry policy updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookRetryPolicyUpdateResponse"
                },
                "examples": {
                  "updated": {
                    "summary": "Full webhook config with the new retry policy",
                    "value": {
                      "message": "Webhook retry policy updated successfully.",
                      "developerId": "dev-123",
                      "url": "https://hooks.example.com/callora",
                      "events": [
                        "new_api_call",
                        "low_balance_alert"
                      ],
                      "retryPolicy": {
                        "maxRetries": 5,
                        "baseDelayMs": 2000
                      },
                      "createdAt": "2026-07-27T09:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Retry policy values are out of range or missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "maxRetriesOutOfRange": {
                    "summary": "maxRetries exceeds the allowed maximum",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "retryPolicy.maxRetries must be between 0 and 10"
                      },
                      "requestId": "req-webhook-retry-patch-400-range",
                      "timestamp": "2026-07-27T09:21:00.000Z"
                    }
                  },
                  "emptyRetryPolicy": {
                    "summary": "retryPolicy object provided but empty",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "retryPolicy must include maxRetries or baseDelayMs when provided"
                      },
                      "requestId": "req-webhook-retry-patch-400-empty",
                      "timestamp": "2026-07-27T09:21:30.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No webhook registered for this developer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "Developer has no registered webhook",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "No webhook registered for this developer."
                      },
                      "requestId": "req-webhook-retry-patch-404",
                      "timestamp": "2026-07-27T09:22:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks/deliver/{developerId}": {
      "post": {
        "summary": "Deliver a signed webhook event",
        "description": "Receives a signed webhook event payload from an external system. The request must include an HMAC-SHA256 signature in the `X-Callora-Signature-256` header, an ISO-8601 timestamp in `X-Callora-Timestamp`, and a unique nonce in `X-Callora-Nonce`. The signed payload is `<timestamp>.<nonce>.<rawBody>`. The signature is verified against all active secrets (current and grace-period previous) using constant-time comparison. Reused nonces and timestamps outside the tolerance window are rejected. Failure responses never identify which key matched.\n",
        "parameters": [
          {
            "name": "developerId",
            "in": "path",
            "required": true,
            "description": "Developer identifier.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$"
            },
            "examples": {
              "valid": {
                "summary": "Valid developer ID",
                "value": "dev-123"
              }
            }
          },
          {
            "name": "X-Callora-Signature-256",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 of `<timestamp>.<nonce>.<rawBody>`, prefixed with `sha256=`. Compared in constant time against the current secret and any previous secret still inside the rotation grace window. Failure responses never identify which key matched.\n",
            "schema": {
              "type": "string"
            },
            "examples": {
              "signature": {
                "summary": "Example signature header",
                "value": "sha256=abc123def456..."
              }
            }
          },
          {
            "name": "X-Callora-Timestamp",
            "in": "header",
            "required": true,
            "description": "ISO-8601 timestamp of when the event was sent. Rejected when outside the configured skew window.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "ts": {
                "summary": "Example timestamp header",
                "value": "2026-07-27T09:30:00.000Z"
              }
            }
          },
          {
            "name": "X-Callora-Nonce",
            "in": "header",
            "required": true,
            "description": "Unique request nonce (16–128 URL-safe characters). Bound into the HMAC and persisted for the timestamp window so replays are rejected.\n",
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._-]{16,128}$"
            },
            "examples": {
              "nonce": {
                "summary": "Example nonce header",
                "value": "nonce-7c9e6679-7425-40de"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDeliveryPayload"
              },
              "examples": {
                "newApiCall": {
                  "summary": "Deliver a new_api_call event",
                  "value": {
                    "event": "new_api_call",
                    "timestamp": "2026-07-27T09:30:00.000Z",
                    "developerId": "dev-123",
                    "data": {
                      "apiId": "api-456",
                      "endpoint": "/v1/checkout",
                      "method": "POST",
                      "statusCode": 200,
                      "latencyMs": 145,
                      "creditsUsed": 10
                    }
                  }
                },
                "settlementCompleted": {
                  "summary": "Deliver a settlement_completed event",
                  "value": {
                    "event": "settlement_completed",
                    "timestamp": "2026-07-27T09:35:00.000Z",
                    "developerId": "dev-123",
                    "data": {
                      "settlementId": "stl-789",
                      "amountCredits": 500,
                      "currency": "XLM"
                    }
                  }
                },
                "lowBalanceAlert": {
                  "summary": "Deliver a low_balance_alert event",
                  "value": {
                    "event": "low_balance_alert",
                    "timestamp": "2026-07-27T09:40:00.000Z",
                    "developerId": "dev-123",
                    "data": {
                      "currentBalance": 50,
                      "thresholdCredits": 100
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook delivery accepted and payload echoed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryResponse"
                },
                "examples": {
                  "accepted": {
                    "summary": "Delivery accepted — payload echoed back",
                    "value": {
                      "message": "Webhook delivery accepted.",
                      "body": {
                        "event": "new_api_call",
                        "timestamp": "2026-07-27T09:30:00.000Z",
                        "developerId": "dev-123",
                        "data": {
                          "apiId": "api-456",
                          "endpoint": "/v1/checkout",
                          "method": "POST",
                          "statusCode": 200,
                          "latencyMs": 145,
                          "creditsUsed": 10
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Signature headers are missing or the payload is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "missingSignature": {
                    "summary": "X-Callora-Signature-256 or X-Callora-Timestamp header absent",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "BAD_REQUEST",
                        "message": "Missing required webhook signature headers"
                      },
                      "requestId": "req-webhook-deliver-400-sig",
                      "timestamp": "2026-07-27T09:31:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "HMAC signature verification failed, timestamp outside the skew window, or nonce replayed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "invalidSignature": {
                    "summary": "Signature does not match any active secret",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Webhook signature verification failed"
                      },
                      "requestId": "req-webhook-deliver-401-invalid",
                      "timestamp": "2026-07-27T09:32:00.000Z"
                    }
                  },
                  "nonceReplayed": {
                    "summary": "Nonce was already consumed (replay)",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "UNAUTHORIZED",
                        "message": "Webhook signature verification failed"
                      },
                      "requestId": "req-webhook-deliver-401-replay",
                      "timestamp": "2026-07-27T09:32:30.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No webhook registered for this developer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardErrorEnvelope"
                },
                "examples": {
                  "notFound": {
                    "summary": "Developer has no registered webhook",
                    "value": {
                      "success": false,
                      "error": {
                        "code": "NOT_FOUND",
                        "message": "No webhook registered for this developer."
                      },
                      "requestId": "req-webhook-deliver-404",
                      "timestamp": "2026-07-27T09:33:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/forecast": {
      "get": {
        "operationId": "getBillingForecast",
        "summary": "Forecast next-period billing spend",
        "description": "Forecasts the authenticated user's next-period bill based on their historical run rate over a specified lookback window.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lookbackDays",
            "in": "query",
            "description": "Number of past days used to calculate current daily run rate (Min: 1, Max: 90).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            }
          },
          {
            "name": "period",
            "in": "query",
            "description": "Target forecast period.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "month",
                "next_30_days",
                "week",
                "day",
                "quarter"
              ],
              "default": "month"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Billing forecast successfully calculated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingForecastResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Historical usage data is currently unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "adminApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-admin-api-key"
      }
    },
    "schemas": {
      "Subscription": {
        "type": "object",
        "description": "A user's subscription to a marketplace API.",
        "required": [
          "id",
          "user_id",
          "api_id",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Subscription UUID"
          },
          "user_id": {
            "type": "string",
            "description": "ID of the subscribing user"
          },
          "api_id": {
            "type": "integer",
            "description": "ID of the subscribed API"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "cancelled"
            ],
            "description": "Current subscription status"
          },
          "metering_limit": {
            "type": "integer",
            "nullable": true,
            "description": "Maximum calls per calendar month; null means unlimited"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "cancelled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "QuotaRequest": {
        "type": "object",
        "description": "A developer quota increase request and its current resolution state.",
        "required": [
          "id",
          "developerId",
          "requestedTier",
          "reason",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique request ID (UUID v4)"
          },
          "developerId": {
            "type": "string",
            "description": "The developer's user ID (from auth)"
          },
          "requestedTier": {
            "type": "string",
            "enum": [
              "free",
              "pro",
              "enterprise"
            ],
            "description": "Requested plan tier"
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 1000,
            "description": "Developer-provided justification"
          },
          "requestedOverrides": {
            "type": "object",
            "description": "Optional specific limits to override in addition to the tier",
            "properties": {
              "monthlyCallLimit": {
                "type": "integer",
                "minimum": 1,
                "description": "Requested monthly API call cap"
              },
              "rateLimitMaxRequests": {
                "type": "integer",
                "minimum": 1,
                "description": "Requested per-window rate-limit ceiling"
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ],
            "description": "Current resolution state"
          },
          "adminNotes": {
            "type": "string",
            "description": "Admin-provided notes on the approval or rejection decision"
          },
          "resolvedBy": {
            "type": "string",
            "description": "Actor ID (admin) who resolved the request"
          },
          "resolvedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the request was resolved"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the request was submitted"
          }
        }
      },
      "QuotaRequestCreate": {
        "type": "object",
        "description": "Payload for submitting a new quota increase request.",
        "required": [
          "requested_tier",
          "reason"
        ],
        "properties": {
          "requested_tier": {
            "type": "string",
            "enum": [
              "free",
              "pro",
              "enterprise"
            ],
            "description": "Desired plan tier"
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 1000,
            "description": "Justification for the upgrade (10–1000 characters)"
          },
          "requested_overrides": {
            "type": "object",
            "description": "Optional specific limit overrides to request alongside the tier upgrade",
            "properties": {
              "monthly_call_limit": {
                "type": "integer",
                "minimum": 1,
                "description": "Requested monthly API call cap"
              },
              "rate_limit_max_requests": {
                "type": "integer",
                "minimum": 1,
                "description": "Requested per-window rate-limit ceiling"
              }
            }
          }
        }
      },
      "PluginManifest": {
        "type": "object",
        "required": [
          "id",
          "name",
          "version",
          "hooks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 3,
            "maxLength": 64,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$"
          },
          "description": {
            "type": "string",
            "maxLength": 512
          },
          "author": {
            "type": "string",
            "maxLength": 128
          },
          "hooks": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "before_charge",
                "after_charge",
                "on_refund",
                "on_quota_exceeded"
              ]
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PluginRecord": {
        "type": "object",
        "required": [
          "manifest",
          "status",
          "created_at"
        ],
        "properties": {
          "manifest": {
            "$ref": "#/components/schemas/PluginManifest"
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "installed"
            ]
          },
          "installed_by": {
            "type": "string",
            "nullable": true
          },
          "installed_at": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "BillingDeductRequest": {
        "type": "object",
        "required": [
          "requestId",
          "apiId",
          "endpointId",
          "apiKeyId",
          "amountUsdc"
        ],
        "properties": {
          "requestId": {
            "type": "string"
          },
          "developerId": {
            "type": "string",
            "description": "Optional developer identifier. If provided, it must be a non-empty string. When omitted, the authenticated user ID is used."
          },
          "apiId": {
            "type": "string"
          },
          "endpointId": {
            "type": "string"
          },
          "apiKeyId": {
            "type": "string"
          },
          "amountUsdc": {
            "type": "string"
          },
          "idempotencyKey": {
            "type": "string"
          }
        }
      },
      "BillingDeductResponse": {
        "type": "object",
        "required": [
          "success",
          "usageEventId",
          "stellarTxHash",
          "alreadyProcessed"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "usageEventId": {
            "type": "string"
          },
          "stellarTxHash": {
            "type": "string"
          },
          "alreadyProcessed": {
            "type": "boolean"
          }
        }
      },
      "BillingBulkDeductEntry": {
        "type": "object",
        "required": [
          "events",
          "stats",
          "period"
        ],
        "properties": {
          "requestId": {
            "type": "string"
          },
          "apiId": {
            "type": "string"
          },
          "endpointId": {
            "type": "string"
          },
          "apiKeyId": {
            "type": "string"
          },
          "amountUsdc": {
            "type": "string",
            "description": "Positive decimal string with up to 7 fractional digits"
          }
        }
      },
      "BillingBulkDeductRequest": {
        "type": "object",
        "required": [
          "entries"
        ],
        "properties": {
          "entries": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/BillingBulkDeductEntry"
            }
          },
          "idempotencyKey": {
            "type": "string"
          }
        }
      },
      "BillingBulkDeductEntryResult": {
        "type": "object",
        "required": [
          "requestId",
          "success",
          "usageEventId",
          "alreadyProcessed",
          "deductionApplied",
          "reconciliationRequired"
        ],
        "properties": {
          "requestId": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          },
          "usageEventId": {
            "type": "string"
          },
          "stellarTxHash": {
            "type": "string"
          },
          "alreadyProcessed": {
            "type": "boolean"
          },
          "deductionApplied": {
            "type": "boolean"
          },
          "reconciliationRequired": {
            "type": "boolean"
          }
        }
      },
      "BillingBulkDeductResponse": {
        "type": "object",
        "required": [
          "success",
          "entryCount",
          "deductedCount",
          "totalDeductedAmountUsdc",
          "results"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "entryCount": {
            "type": "integer"
          },
          "deductedCount": {
            "type": "integer"
          },
          "totalDeductedAmountUsdc": {
            "type": "string"
          },
          "stellarTxHash": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillingBulkDeductEntryResult"
            }
          }
        }
      },
      "BillingBulkDeductErrorResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": [
          "events",
          "stats",
          "period"
        ],
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "apiId",
                "endpoint",
                "occurredAt",
                "revenue"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier for the usage event."
                },
                "apiId": {
                  "type": "string",
                  "description": "Identifier of the API that was called."
                },
                "endpoint": {
                  "type": "string",
                  "description": "API endpoint path that was invoked."
                },
                "occurredAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp when the call occurred."
                },
                "revenue": {
                  "type": "string",
                  "description": "Revenue generated by this event in smallest USDC units (string to avoid precision loss)."
                }
              }
            }
          },
          "stats": {
            "type": "object",
            "required": [
              "totalCalls",
              "totalSpent",
              "breakdownByApi"
            ],
            "properties": {
              "totalCalls": {
                "type": "integer",
                "description": "Total number of API calls in the period."
              },
              "totalSpent": {
                "type": "string",
                "description": "Total spend in smallest USDC units (string to avoid precision loss)."
              },
              "breakdownByApi": {
                "type": "array",
                "description": "Per-API aggregated call count and revenue.",
                "items": {
                  "type": "object",
                  "required": [
                    "apiId",
                    "calls",
                    "revenue"
                  ],
                  "properties": {
                    "apiId": {
                      "type": "string"
                    },
                    "calls": {
                      "type": "integer"
                    },
                    "revenue": {
                      "type": "string"
                    }
                  }
                }
              },
              "buckets": {
                "type": "array",
                "description": "Time-bucketed aggregation (present when groupBy is supplied).",
                "items": {
                  "type": "object",
                  "required": [
                    "period",
                    "calls",
                    "revenue"
                  ],
                  "properties": {
                    "period": {
                      "type": "string",
                      "description": "Bucket label (e.g. YYYY-MM-DD for groupBy=day)."
                    },
                    "calls": {
                      "type": "integer"
                    },
                    "revenue": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "period": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "description": "The effective time range covered by this response.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "pagination": {
            "type": "object",
            "description": "Pagination metadata. Shape varies by pagination mode: offset pagination includes limit/offset/hasMore; cursor pagination includes limit/nextCursor.",
            "properties": {
              "limit": {
                "type": "integer",
                "description": "Page size used for this request."
              },
              "offset": {
                "type": "integer",
                "description": "Offset applied for this request (offset pagination only)."
              },
              "hasMore": {
                "type": "boolean",
                "description": "Whether additional pages exist."
              },
              "nextCursor": {
                "type": "string",
                "description": "Opaque base64 cursor to pass as the `cursor` query parameter for the next page (cursor pagination only)."
              }
            }
          },
          "requestId": {
            "type": "string",
            "description": "Correlation ID for this request, propagated from the X-Request-Id header."
          }
        }
      },
      "AdminUsageSnapshot": {
        "type": "object",
        "required": [
          "developerId",
          "totalEvents",
          "settledEvents",
          "unsettledEvents",
          "totalAmountUsdc",
          "settledAmountUsdc",
          "unsettledAmountUsdc",
          "apiCount",
          "endpointCount",
          "firstEventAt",
          "lastEventAt",
          "statusCodes"
        ],
        "properties": {
          "developerId": {
            "type": "string"
          },
          "totalEvents": {
            "type": "integer"
          },
          "settledEvents": {
            "type": "integer"
          },
          "unsettledEvents": {
            "type": "integer"
          },
          "totalAmountUsdc": {
            "type": "number"
          },
          "settledAmountUsdc": {
            "type": "number"
          },
          "unsettledAmountUsdc": {
            "type": "number"
          },
          "apiCount": {
            "type": "integer"
          },
          "endpointCount": {
            "type": "integer"
          },
          "firstEventAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastEventAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "statusCodes": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          }
        }
      },
      "AdminUsageSnapshotResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/AdminUsageSnapshot"
          }
        }
      },
      "AdminUsageResetResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "developerId",
              "reset",
              "priorValues"
            ],
            "properties": {
              "developerId": {
                "type": "string"
              },
              "reset": {
                "type": "boolean"
              },
              "priorValues": {
                "$ref": "#/components/schemas/AdminUsageSnapshot"
              }
            }
          }
        }
      },
      "ApisListResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiDetailsResponse"
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "limit",
              "hasMore"
            ],
            "properties": {
              "limit": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "description": "Opaque base64 cursor for the next page. Absent when hasMore is false."
              }
            }
          }
        }
      },
      "ApiCreateRequest": {
        "type": "object",
        "required": [
          "name",
          "base_url",
          "category",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "base_url": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "path",
                "method",
                "price_per_call_usdc"
              ],
              "properties": {
                "path": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "price_per_call_usdc": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ApiCreateResponse": {
        "type": "object",
        "required": [
          "id",
          "developer_id",
          "name",
          "base_url",
          "category",
          "status",
          "endpoints"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "developer_id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "base_url": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "api_id",
                "path",
                "method",
                "price_per_call_usdc"
              ],
              "properties": {
                "id": {
                  "type": "integer"
                },
                "api_id": {
                  "type": "integer"
                },
                "path": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "price_per_call_usdc": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "nullable": true
                },
                "created_at": {
                  "type": "string"
                },
                "updated_at": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "BulkEndpointRegistrationRequest": {
        "type": "object",
        "required": [
          "endpoints"
        ],
        "properties": {
          "endpoints": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "required": [
                "path",
                "method",
                "price_per_call_usdc"
              ],
              "properties": {
                "path": {
                  "type": "string",
                  "description": "URL path starting with /"
                },
                "method": {
                  "type": "string",
                  "enum": [
                    "GET",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE",
                    "HEAD",
                    "OPTIONS"
                  ]
                },
                "price_per_call_usdc": {
                  "type": "string",
                  "description": "Non-negative decimal string (e.g. \"0.01\")"
                },
                "description": {
                  "type": "string",
                  "description": "Optional human-readable description"
                }
              }
            }
          }
        }
      },
      "BulkEndpointRegistrationResponse": {
        "type": "object",
        "required": [
          "endpoints"
        ],
        "properties": {
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "api_id",
                "path",
                "method",
                "price_per_call_usdc"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "Auto-generated endpoint ID"
                },
                "api_id": {
                  "type": "integer",
                  "description": "Owning API ID"
                },
                "path": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "price_per_call_usdc": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "ApiDetailsResponse": {
        "type": "object",
        "required": [
          "id",
          "name",
          "base_url",
          "category",
          "status",
          "developer",
          "endpoints"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "base_url": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "developer": {
            "type": "object",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "api_id",
                "path",
                "method",
                "price_per_call_usdc"
              ],
              "properties": {
                "id": {
                  "type": "integer"
                },
                "api_id": {
                  "type": "integer"
                },
                "path": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "price_per_call_usdc": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "DeveloperRevenueResponse": {
        "type": "object",
        "required": [
          "summary",
          "settlements",
          "pagination"
        ],
        "properties": {
          "summary": {
            "type": "object",
            "required": [
              "total_earned",
              "pending",
              "available_to_withdraw"
            ],
            "properties": {
              "total_earned": {
                "type": "number"
              },
              "pending": {
                "type": "number"
              },
              "available_to_withdraw": {
                "type": "number"
              }
            }
          },
          "settlements": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "developerId",
                "amount",
                "status",
                "created_at"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "developerId": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "status": {
                  "type": "string"
                },
                "tx_hash": {
                  "type": "string",
                  "nullable": true
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "pagination": {
            "type": "object",
            "required": [
              "limit",
              "offset",
              "total"
            ],
            "properties": {
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          }
        }
      },
      "DeveloperApiKey": {
        "type": "object",
        "required": [
          "id",
          "prefix",
          "created_at",
          "last_used_at",
          "revoked_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "DeveloperApiKeysResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeveloperApiKey"
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "limit",
              "nextCursor",
              "hasMore"
            ],
            "properties": {
              "limit": {
                "type": "integer"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              },
              "hasMore": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "DeveloperUsageSummaryResponse": {
        "type": "object",
        "required": [
          "summary",
          "breakdownByApi",
          "buckets",
          "period"
        ],
        "properties": {
          "summary": {
            "type": "object",
            "required": [
              "totalCalls",
              "totalRevenue",
              "activeApis"
            ],
            "properties": {
              "totalCalls": {
                "type": "integer"
              },
              "totalRevenue": {
                "type": "string"
              },
              "activeApis": {
                "type": "integer"
              }
            }
          },
          "breakdownByApi": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "apiId",
                "calls",
                "revenue"
              ],
              "properties": {
                "apiId": {
                  "type": "string"
                },
                "calls": {
                  "type": "integer"
                },
                "revenue": {
                  "type": "string"
                }
              }
            }
          },
          "buckets": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "period",
                "calls",
                "revenue"
              ],
              "properties": {
                "period": {
                  "type": "string"
                },
                "calls": {
                  "type": "integer"
                },
                "revenue": {
                  "type": "string"
                }
              }
            }
          },
          "period": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              }
            }
          }
        }
      },
      "HealthDependenciesResponse": {
        "type": "object",
        "required": [
          "timestamp",
          "dependencies"
        ],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "dependencies": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "required": [
                "status"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "degraded",
                    "down"
                  ]
                },
                "responseTime": {
                  "type": "number",
                  "description": "Response time in milliseconds"
                },
                "error": {
                  "type": "string",
                  "description": "Sanitized error message"
                }
              }
            }
          }
        }
      },
      "GatewayHealthResponse": {
        "type": "object",
        "required": [
          "apiSlug",
          "latency",
          "breaker"
        ],
        "properties": {
          "apiSlug": {
            "type": "string"
          },
          "latency": {
            "type": "object",
            "required": [
              "p50",
              "p95"
            ],
            "properties": {
              "p50": {
                "type": "number",
                "nullable": true,
                "description": "P50 latency in milliseconds (null if no traffic yet)"
              },
              "p95": {
                "type": "number",
                "nullable": true,
                "description": "P95 latency in milliseconds (null if no traffic yet)"
              }
            }
          },
          "breaker": {
            "type": "object",
            "required": [
              "state"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "closed",
                  "open",
                  "half-open"
                ]
              }
            }
          }
        }
      },
      "RateLimitHealthResponse": {
        "type": "object",
        "description": "Operational health response for the rate-limit subsystem.",
        "required": [
          "status",
          "timestamp",
          "dependencies"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "dependencies": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/RateLimitDependencyStatus"
            }
          }
        }
      },
      "RateLimitCheckResponse": {
        "type": "object",
        "description": "Non-consuming rate-limit budget check for the authenticated user.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "deny"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "rate_limit_exceeded"
            ]
          },
          "retryAfterMs": {
            "type": "integer",
            "minimum": 0,
            "description": "Milliseconds until the current rate-limit window resets"
          }
        }
      },
      "RateLimitDependencyStatus": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ]
          },
          "responseTime": {
            "type": "number",
            "description": "Probe response time in milliseconds"
          },
          "error": {
            "type": "string",
            "description": "Safe error identifier when the dependency is unavailable"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "ErrorCode": {
        "type": "string",
        "enum": [
          "BAD_REQUEST",
          "UNAUTHORIZED",
          "FORBIDDEN",
          "NOT_FOUND",
          "PAYMENT_REQUIRED",
          "TOO_MANY_REQUESTS",
          "CONFLICT",
          "INTERNAL_SERVER_ERROR",
          "BAD_GATEWAY",
          "SERVICE_UNAVAILABLE",
          "GATEWAY_TIMEOUT",
          "VALIDATION_ERROR",
          "INVALID_BODY",
          "INVALID_QUERY",
          "INVALID_PARAMS",
          "INVALID_VALUE",
          "GATEWAY_AUTH_CONTEXT_MISSING",
          "UPSTREAM_TARGET_BLOCKED",
          "INSUFFICIENT_BALANCE",
          "SOROBAN_RPC_TIMEOUT",
          "SOROBAN_RPC_ERROR",
          "BILLING_DEDUCTION_FAILED",
          "RECONCILIATION_REQUIRED",
          "BILLING_REQUEST_NOT_FOUND",
          "FORECAST_DATA_UNAVAILABLE",
          "DEVELOPER_NOT_FOUND",
          "API_ACCESS_FORBIDDEN",
          "API_KEY_NOT_FOUND",
          "API_KEY_FORBIDDEN",
          "MISSING_REFRESH_TOKEN",
          "INVALID_REFRESH_TOKEN",
          "REVOKED_TOKEN",
          "EXPIRED_TOKEN",
          "REFRESH_FAILED",
          "REVOKE_FAILED",
          "NOT_AUTHENTICATED",
          "TOKEN_INFO_FAILED",
          "VAULT_NOT_FOUND",
          "VAULT_BALANCE_RETRIEVAL_FAILED",
          "MISSING_AMOUNT",
          "INVALID_AMOUNT_TYPE",
          "INVALID_AMOUNT_FORMAT",
          "INVALID_NETWORK",
          "NETWORK_MISMATCH",
          "INVALID_SOURCE_ACCOUNT",
          "INVALID_TRANSACTION_INPUT",
          "SOURCE_ACCOUNT_NOT_FOUND",
          "INVALID_CONTRACT_ID",
          "NETWORK_UNAVAILABLE",
          "TRANSACTION_BUILD_FAILED",
          "INTERNAL_ERROR",
          "INVALID_WEBHOOK_REGISTRATION",
          "INVALID_WEBHOOK_EVENT_TYPES",
          "WEBHOOK_NOT_FOUND",
          "INVALID_WEBHOOK_URL",
          "WEBHOOK_URL_VALIDATION_FAILED",
          "MISSING_WEBHOOK_SIGNATURE_HEADERS",
          "INVALID_WEBHOOK_TIMESTAMP",
          "WEBHOOK_TIMESTAMP_OUT_OF_WINDOW",
          "MALFORMED_WEBHOOK_SIGNATURE",
          "INVALID_WEBHOOK_SIGNATURE",
          "MALFORMED_WEBHOOK_NONCE",
          "WEBHOOK_NONCE_REPLAYED",
          "INVALID_DELIVERY_ID",
          "INVALID_RETRY_POLICY",
          "DLQ_ENTRY_NOT_FOUND",
          "INVALID_IP_FORMAT",
          "IP_NOT_ALLOWED",
          "DATABASE_NOT_AVAILABLE",
          "IDEMPOTENCY_CONFLICT",
          "IDEMPOTENCY_IN_PROGRESS",
          "SIMULATION_FAILED",
          "INVALID_AUTH_HEADER",
          "MISSING_TOKEN",
          "INVALID_TOKEN",
          "MISSING_CLAIMS",
          "TOKEN_EXPIRED",
          "TOKEN_NOT_ACTIVE",
          "QUOTA_REQUEST_NOT_FOUND",
          "QUOTA_REQUEST_ALREADY_RESOLVED",
          "INVALID_QUOTA_REQUEST",
          "REQUEST_TIMEOUT",
          "REQUEST_BODY_TOO_LARGE",
          "UNSUPPORTED_MEDIA_TYPE",
          "UNPROCESSABLE_ENTITY",
          "USAGE_AGGREGATE_NOT_FOUND",
          "INVALID_EXPORT_SCHEDULE",
          "EXPORT_SCHEDULE_NOT_FOUND",
          "MISSING_AUTH_FIELDS",
          "AUTH_NOT_IMPLEMENTED",
          "COMPONENT_NOT_CONFIGURED",
          "INVALID_ENTRY_ID",
          "AUDIT_ENTRY_NOT_FOUND",
          "AUDIT_ACTION_NOT_REPLAYABLE",
          "AUDIT_DETAILS_INCOMPLETE",
          "LOG_ENTRY_NOT_FOUND",
          "BULK_QUOTA_UPDATE_FAILED",
          "STALE_FORWARDED_IDENTITY",
          "REPLAYED_FORWARDED_IDENTITY"
        ],
        "description": "Canonical Callora backend error code."
      },
      "Dispute": {
        "type": "object",
        "required": [
          "id",
          "usage_event_id",
          "opened_by",
          "reason",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "usage_event_id": {
            "type": "string"
          },
          "opened_by": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "OPEN",
              "REFUNDED",
              "UPHELD"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resolved_by": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "HealthChecks": {
        "type": "object",
        "description": "Per-dependency health check statuses.",
        "required": [
          "api"
        ],
        "properties": {
          "api": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ],
            "description": "API server health"
          },
          "database": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ],
            "description": "Database connection health"
          },
          "soroban_rpc": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ],
            "description": "Soroban RPC connectivity"
          },
          "horizon": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ],
            "description": "Horizon API connectivity"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "description": "Health check response in success envelope.",
        "required": [
          "success",
          "data",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ok",
                  "degraded",
                  "down"
                ],
                "description": "Aggregate health status"
              },
              "service": {
                "type": "string",
                "description": "Service name (simple mode)"
              },
              "version": {
                "type": "string",
                "description": "Application version"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "checks": {
                "$ref": "#/components/schemas/HealthChecks"
              }
            }
          },
          "requestId": {
            "type": "string",
            "description": "Correlation ID for the request"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DisputeEvent": {
        "type": "object",
        "required": [
          "id",
          "dispute_id",
          "actor",
          "action",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "dispute_id": {
            "type": "string"
          },
          "actor": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OpenDisputeRequest": {
        "type": "object",
        "required": [
          "usage_event_id",
          "reason"
        ],
        "properties": {
          "usage_event_id": {
            "type": "string",
            "minLength": 1
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          }
        }
      },
      "ResolveDisputeRequest": {
        "type": "object",
        "required": [
          "resolution"
        ],
        "properties": {
          "resolution": {
            "type": "string",
            "enum": [
              "REFUNDED",
              "UPHELD"
            ]
          },
          "notes": {
            "type": "string",
            "maxLength": 1000
          }
        }
      },
      "ErrorRecord": {
        "type": "object",
        "required": [
          "id",
          "code",
          "message",
          "statusCode",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "statusCode": {
            "type": "integer"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorRecordResponse": {
        "type": "object",
        "required": [
          "success",
          "data",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ErrorRecord"
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorsListResponse": {
        "type": "object",
        "required": [
          "success",
          "data",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "required": [
              "errors"
            ],
            "properties": {
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ErrorRecord"
                }
              }
            }
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorCreateRequest": {
        "type": "object",
        "required": [
          "code",
          "message",
          "statusCode"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "statusCode": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 1000
          }
        }
      },
      "ErrorUpdateRequest": {
        "type": "object",
        "description": "At least one field must be provided.",
        "minProperties": 1,
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "statusCode": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 1000
          }
        }
      },
      "StandardErrorEnvelope": {
        "type": "object",
        "required": [
          "success",
          "error",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SpikeSeverity": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "SpikeRunResponse": {
        "type": "object",
        "required": [
          "success",
          "message",
          "delay",
          "elapsed"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          },
          "delay": {
            "type": "integer"
          },
          "elapsed": {
            "type": "integer"
          }
        }
      },
      "SpikeRecord": {
        "type": "object",
        "required": [
          "id",
          "label",
          "severity",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "minLength": 1
          },
          "severity": {
            "$ref": "#/components/schemas/SpikeSeverity"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SpikeRecordsResponse": {
        "type": "object",
        "required": [
          "records"
        ],
        "properties": {
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpikeRecord"
            }
          }
        }
      },
      "SpikeCreateRequest": {
        "type": "object",
        "required": [
          "label",
          "severity"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          },
          "severity": {
            "$ref": "#/components/schemas/SpikeSeverity"
          }
        }
      },
      "SpikeUpdateRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          },
          "severity": {
            "$ref": "#/components/schemas/SpikeSeverity"
          }
        }
      },
      "WebhookEventType": {
        "type": "string",
        "enum": [
          "new_api_call",
          "settlement_completed",
          "low_balance_alert"
        ],
        "description": "Supported webhook event types. Subscribe to one or more in the `events` array when registering.\n"
      },
      "WebhookRetryPolicy": {
        "type": "object",
        "description": "Controls reattempt behaviour when the target URL does not return 2xx. At least one of `maxRetries` or `baseDelayMs` must be provided.\n",
        "minProperties": 1,
        "properties": {
          "maxRetries": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "description": "Maximum number of delivery attempts after the initial failure (0–10)."
          },
          "baseDelayMs": {
            "type": "integer",
            "minimum": 100,
            "maximum": 60000,
            "description": "Base delay in milliseconds before the first retry. Subsequent retries use exponential back-off up to this ceiling (100–60 000 ms).\n"
          }
        },
        "additionalProperties": false
      },
      "WebhookRegisterRequest": {
        "type": "object",
        "required": [
          "developerId",
          "url",
          "events"
        ],
        "description": "Request body for POST /api/webhooks. The `events` array must be non-empty and contain only supported WebhookEventType values. The optional `secret` seeds the HMAC-SHA256 signing key; when omitted the server generates a 64-character hex secret automatically.\n",
        "properties": {
          "developerId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$",
            "description": "Developer identifier (3–128 chars, alphanumeric/underscore/hyphen)."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Absolute HTTPS URL that will receive event POST requests. The URL is validated for reachability at registration time.\n"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            },
            "minItems": 1,
            "description": "One or more event types to subscribe to."
          },
          "secret": {
            "type": "string",
            "minLength": 8,
            "maxLength": 256,
            "description": "Optional HMAC signing secret (8–256 chars). If omitted the server generates one automatically.\n"
          },
          "retryPolicy": {
            "$ref": "#/components/schemas/WebhookRetryPolicy"
          }
        },
        "additionalProperties": false
      },
      "WebhookRegisterResponse": {
        "type": "object",
        "required": [
          "message",
          "developerId",
          "url",
          "events"
        ],
        "description": "Response body for a successful POST /api/webhooks (201).",
        "properties": {
          "message": {
            "type": "string",
            "example": "Webhook registered successfully."
          },
          "developerId": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          }
        }
      },
      "WebhookConfig": {
        "type": "object",
        "required": [
          "developerId",
          "url",
          "events"
        ],
        "description": "Webhook configuration returned by GET /api/webhooks/{developerId}. Signing secrets are never included in this response.\n",
        "properties": {
          "developerId": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "retryPolicy": {
            "$ref": "#/components/schemas/WebhookRetryPolicy"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookDeleteResponse": {
        "type": "object",
        "required": [
          "message"
        ],
        "description": "Response body for a successful DELETE /api/webhooks/{developerId}.",
        "properties": {
          "message": {
            "type": "string",
            "example": "Webhook removed."
          }
        }
      },
      "WebhookRotateSecretResponse": {
        "type": "object",
        "required": [
          "message",
          "developerId",
          "secret"
        ],
        "description": "Response body for a successful POST /api/webhooks/{developerId}/rotate-secret. The new secret is returned once only — store it immediately.\n",
        "properties": {
          "message": {
            "type": "string",
            "example": "Webhook secret rotated successfully."
          },
          "developerId": {
            "type": "string"
          },
          "secret": {
            "type": "string",
            "description": "The new HMAC-SHA256 signing secret (64 hex chars).",
            "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
          },
          "previous_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC timestamp after which the previous secret is no longer valid. Consumers should rotate to the new secret before this time.\n"
          }
        }
      },
      "WebhookRetryPolicyUpdateRequest": {
        "type": "object",
        "description": "Request body for PATCH /api/webhooks/{developerId}/retry-policy. The `retryPolicy` object must include at least one field.\n",
        "properties": {
          "retryPolicy": {
            "$ref": "#/components/schemas/WebhookRetryPolicy"
          }
        },
        "additionalProperties": false
      },
      "WebhookRetryPolicyUpdateResponse": {
        "type": "object",
        "required": [
          "message",
          "developerId",
          "url",
          "events"
        ],
        "description": "Response body for a successful PATCH /api/webhooks/{developerId}/retry-policy. Returns the full webhook config with the updated retry policy applied.\n",
        "properties": {
          "message": {
            "type": "string",
            "example": "Webhook retry policy updated successfully."
          },
          "developerId": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "retryPolicy": {
            "$ref": "#/components/schemas/WebhookRetryPolicy"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookDeliveryPayload": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "developerId",
          "data"
        ],
        "description": "Signed event payload for POST /api/webhooks/deliver/{developerId}. The request must carry an `X-Callora-Signature-256` header (HMAC-SHA256 over the raw body) and an `X-Callora-Timestamp` header (Unix seconds).\n",
        "properties": {
          "event": {
            "$ref": "#/components/schemas/WebhookEventType"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 datetime when the event was emitted."
          },
          "developerId": {
            "type": "string",
            "description": "Developer for whom this event is intended."
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Event-specific payload. Keys and value types depend on the event type (e.g. `apiId`, `latencyMs` for `new_api_call`).\n"
          }
        },
        "additionalProperties": false
      },
      "WebhookDeliveryResponse": {
        "type": "object",
        "required": [
          "message",
          "body"
        ],
        "description": "Response body for a successful POST /api/webhooks/deliver/{developerId}. The received payload is echoed back for debugging.\n",
        "properties": {
          "message": {
            "type": "string",
            "example": "Webhook delivery accepted."
          },
          "body": {
            "$ref": "#/components/schemas/WebhookDeliveryPayload"
          }
        }
      },
      "TenantPlan": {
        "type": "string",
        "enum": [
          "starter",
          "growth",
          "enterprise"
        ]
      },
      "TenantMetadata": {
        "type": "object",
        "maxProperties": 20,
        "propertyNames": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "additionalProperties": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 256
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            }
          ]
        }
      },
      "TenantRecord": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug",
          "plan",
          "createdBy",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "contactEmail": {
            "type": "string",
            "format": "email"
          },
          "plan": {
            "$ref": "#/components/schemas/TenantPlan"
          },
          "metadata": {
            "$ref": "#/components/schemas/TenantMetadata"
          },
          "createdBy": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TenantCreateRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$"
          },
          "contactEmail": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "plan": {
            "$ref": "#/components/schemas/TenantPlan"
          },
          "metadata": {
            "$ref": "#/components/schemas/TenantMetadata"
          }
        }
      },
      "TenantUpdateRequest": {
        "type": "object",
        "minProperties": 1,
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "contactEmail": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "plan": {
            "$ref": "#/components/schemas/TenantPlan"
          },
          "metadata": {
            "$ref": "#/components/schemas/TenantMetadata"
          }
        }
      },
      "TenantResponse": {
        "type": "object",
        "required": [
          "success",
          "data",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/TenantRecord"
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TenantListResponse": {
        "type": "object",
        "required": [
          "success",
          "data",
          "requestId",
          "timestamp"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TenantRecord"
            }
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BillingForecastResponse": {
        "type": "object",
        "description": "Forecast calculation result payload with exact 7-decimal USDC amounts.",
        "required": [
          "userId",
          "lookbackDays",
          "lookbackStart",
          "lookbackEnd",
          "windowSpentUsdc",
          "dailyRunRateUsdc",
          "forecastPeriod",
          "forecastDays",
          "forecastedAmountUsdc",
          "totalCalls",
          "currency",
          "generatedAt"
        ],
        "properties": {
          "userId": {
            "type": "string",
            "description": "Authenticated user/consumer ID."
          },
          "lookbackDays": {
            "type": "integer",
            "description": "Number of days evaluated for current run rate."
          },
          "lookbackStart": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp starting the lookback window."
          },
          "lookbackEnd": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp ending the lookback window."
          },
          "windowSpentUsdc": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{7}$",
            "description": "Total USDC spent as a consumer during the lookback window, formatted to 7 decimal places."
          },
          "dailyRunRateUsdc": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{7}$",
            "description": "Calculated daily run rate in USDC, formatted to 7 decimal places."
          },
          "forecastPeriod": {
            "type": "string",
            "enum": [
              "month",
              "next_30_days",
              "week",
              "day",
              "quarter"
            ],
            "description": "Selected target forecast period."
          },
          "forecastDays": {
            "type": "integer",
            "description": "Number of days in target forecast period."
          },
          "forecastedAmountUsdc": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{7}$",
            "description": "Forecasted bill amount in USDC, formatted to 7 decimal places."
          },
          "totalCalls": {
            "type": "integer",
            "description": "Total confirmed usage calls recorded during the lookback window."
          },
          "currency": {
            "type": "string",
            "default": "USDC",
            "description": "Currency unit (USDC)."
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp when forecast was computed."
          }
        }
      }
    }
  }
}