{
  "openapi": "3.1.0",
  "info": {
    "title": "Aetherin",
    "version": "v1",
    "description": "Aetherin LLM gateway core API.\n\nTwo authentication schemes are in use:\n\n* Session cookie `aetherin_session` (operator surface: /v1/auth, orgs,\n  keys, usage, budgets, plugins config, billing, admin). Mutating\n  requests authorized by the cookie additionally require the\n  `X-CSRF-Token` header carrying the session's CSRF token (returned by\n  login / me / refresh).\n* Bearer API key (`Authorization: Bearer <key>`) for the data plane\n  (/v1/models, /v1/chat/completions, /v1/embeddings, /v1/providers\n  reads) and for `GET /metrics`.\n\nErrors use a single envelope:\n`{\"error\":{\"code\":\"<stable_code>\",\"message\":\"...\",\"type\":\"<coarse>\",\"request_id\":\"...\"}}`.\n"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "auth",
      "description": "Registration, login, session and account activation"
    },
    {
      "name": "orgs",
      "description": "Organizations and workspaces"
    },
    {
      "name": "team",
      "description": "Organization members and invitations"
    },
    {
      "name": "keys",
      "description": "Workspace API keys"
    },
    {
      "name": "models",
      "description": "Model catalogue and fallback routes"
    },
    {
      "name": "providers",
      "description": "Upstream providers"
    },
    {
      "name": "chat",
      "description": "Data plane: chat completions and embeddings"
    },
    {
      "name": "usage",
      "description": "Usage summary, event list and CSV export"
    },
    {
      "name": "budgets",
      "description": "Per-key spend budgets"
    },
    {
      "name": "billing",
      "description": "Plans, subscription, checkout and invoices"
    },
    {
      "name": "webhooks",
      "description": "Stripe webhook receiver"
    },
    {
      "name": "plugins",
      "description": "Plugin registry and configuration"
    },
    {
      "name": "admin",
      "description": "Deployment administration, pricing governance, feeds and notifications"
    },
    {
      "name": "system",
      "description": "Health, version and metrics"
    }
  ],
  "paths": {
    "/v1/auth/register": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Register a new account",
        "description": "Creates a member account plus a default org and workspace. Answers the user object.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/AuthUser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/auth/login": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Sign in",
        "description": "Verifies credentials, creates a session cookie `aetherin_session` and returns the session CSRF token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session established",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "csrf_token",
                    "user"
                  ],
                  "properties": {
                    "csrf_token": {
                      "type": "string"
                    },
                    "user": {
                      "$ref": "#/components/schemas/AuthUser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/auth/logout": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Sign out",
        "description": "Requires the session CSRF token; invalidates the session server-side and clears the cookie.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "responses": {
          "204": {
            "description": "Session ended"
          },
          "403": {
            "$ref": "#/components/responses/CSRFInvalid"
          }
        }
      }
    },
    "/v1/auth/me": {
      "get": {
        "tags": [
          "auth"
        ],
        "summary": "Current user and organizations",
        "description": "Returns the authenticated user, the organizations the caller may reach and the session CSRF token.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/AuthUser"
                    },
                    "orgs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Org"
                      }
                    },
                    "csrf_token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/auth/refresh": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Rotate the session",
        "description": "Invalidates the current session, issues a fresh one with a new CSRF token and sets the cookie again.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session rotated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "csrf_token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/CSRFInvalid"
          }
        }
      }
    },
    "/v1/auth/activate": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Activate an invited account",
        "description": "Consumes a one-time activation token from the JSON body and sets the account password.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token",
                  "password"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "optional cross-check"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account activated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/auth/activate/{token}": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Activate an invited account (token in path)",
        "description": "Same as POST /v1/auth/activate with the activation token carried in the path; the body may carry only the password (and optional email cross-check).",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": {
                    "type": "string",
                    "format": "password"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account activated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/orgs": {
      "get": {
        "tags": [
          "orgs"
        ],
        "summary": "List organizations",
        "description": "Organizations the caller owns plus those they are a member of. Cursor paginated.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of organizations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "orgs"
        ],
        "summary": "Create an organization",
        "description": "The caller becomes the owner. Requires the session CSRF token.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Organization created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Org"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/CSRFInvalid"
          }
        }
      }
    },
    "/v1/orgs/{id}": {
      "get": {
        "tags": [
          "orgs"
        ],
        "summary": "Get an organization",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Org"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "orgs"
        ],
        "summary": "Rename an organization",
        "description": "Requires the admin role of the organization.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Org"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "orgs"
        ],
        "summary": "Delete an organization",
        "description": "Owner only; removes the org and every resource it owns. Answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "responses": {
          "204": {
            "description": "Organization deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/orgs/{id}/workspaces": {
      "get": {
        "tags": [
          "orgs"
        ],
        "summary": "List workspaces of an organization",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "responses": {
          "200": {
            "description": "Page of workspaces",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspacePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "orgs"
        ],
        "summary": "Create a workspace",
        "description": "Requires the admin role of the organization.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Workspace created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/orgs/{id}/workspaces/{workspaceId}": {
      "get": {
        "tags": [
          "orgs"
        ],
        "summary": "Get a workspace",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/workspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "orgs"
        ],
        "summary": "Rename a workspace",
        "description": "Requires the admin role of the organization.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/workspaceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "orgs"
        ],
        "summary": "Delete a workspace",
        "description": "Owner only; the last workspace of an organization cannot be removed (409).",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/workspaceId"
          }
        ],
        "responses": {
          "204": {
            "description": "Workspace deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/orgs/{id}/members": {
      "get": {
        "tags": [
          "team"
        ],
        "summary": "List organization members",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "responses": {
          "200": {
            "description": "Page of members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/orgs/{id}/members/{memberId}": {
      "patch": {
        "tags": [
          "team"
        ],
        "summary": "Change a member's role",
        "description": "Requires admin role; only an owner may grant owner/admin. Answers the updated member.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/memberId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "billing"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated member",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "team"
        ],
        "summary": "Remove a member",
        "description": "The owner cannot be removed; answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/memberId"
          }
        ],
        "responses": {
          "204": {
            "description": "Member removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/orgs/{id}/invites": {
      "get": {
        "tags": [
          "team"
        ],
        "summary": "List pending invitations",
        "description": "Restricted to org owners and admins.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "responses": {
          "200": {
            "description": "Page of invites",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvitePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "team"
        ],
        "summary": "Invite a member",
        "description": "Creates a pending invite and returns the one-time bearer token plus accept URL (transported to the invitee out of band).",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "role"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "billing"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invite created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InviteCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/orgs/{id}/invites/{inviteId}": {
      "delete": {
        "tags": [
          "team"
        ],
        "summary": "Revoke a pending invitation",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/inviteId"
          }
        ],
        "responses": {
          "204": {
            "description": "Invite revoked"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/invites/{token}/accept": {
      "post": {
        "tags": [
          "team"
        ],
        "summary": "Accept an invitation",
        "description": "Uses the session cookie, or an anonymous JSON body with the invitee email. The invite email must match the account.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "sessionCookie": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Invitation accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invite"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/keys": {
      "get": {
        "tags": [
          "keys"
        ],
        "summary": "List API keys",
        "description": "Keys of one workspace (`workspace_id`), or of every workspace the caller belongs to when omitted. Cursor paginated.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of keys",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "keys"
        ],
        "summary": "Create an API key",
        "description": "Mints a key in a workspace; the plaintext key is returned once in `key`.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspace_id"
                ],
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "budget_usd_monthly": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "rpm_limit": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created (plaintext shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/keys/{id}": {
      "get": {
        "tags": [
          "keys"
        ],
        "summary": "Get an API key",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/keyId"
          }
        ],
        "responses": {
          "200": {
            "description": "Key record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "keys"
        ],
        "summary": "Update an API key",
        "description": "Rename or change budget / rate limit. Requires admin role of the owning org.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/keyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "budget_usd_monthly": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "rpm_limit": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "keys"
        ],
        "summary": "Revoke an API key",
        "description": "Revokes the credential; answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/keyId"
          }
        ],
        "responses": {
          "204": {
            "description": "Key revoked"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/keys/{id}/rotate": {
      "post": {
        "tags": [
          "keys"
        ],
        "summary": "Rotate an API key",
        "description": "Revokes the old credential and mints a replacement; plaintext returned once. Owner role required.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/keyId"
          }
        ],
        "responses": {
          "200": {
            "description": "New key (plaintext shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreated"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/providers": {
      "get": {
        "tags": [
          "providers"
        ],
        "summary": "List providers",
        "description": "Providers of one workspace, or every accessible workspace plus deployment-global ones when `workspace_id` is omitted. Session or Bearer auth.",
        "security": [
          {
            "sessionCookie": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of providers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "providers"
        ],
        "summary": "Create a provider",
        "description": "Records an upstream provider; the credential is sealed and never echoed. Requires admin role.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspace_id",
                  "type"
                ],
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "type": {
                    "type": "string",
                    "description": "openai, anthropic, gemini, openrouter, ..."
                  },
                  "base_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "credentials": {
                    "description": "API key as a string or an object with `api_key`",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "api_key": {
                            "type": "string"
                          }
                        }
                      }
                    ]
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Provider created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provider"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/providers/{id}": {
      "patch": {
        "tags": [
          "providers"
        ],
        "summary": "Update a provider",
        "description": "Change base_url, enabled flag or rotate the credential. Requires admin role.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/providerId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "base_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "credentials": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object"
                      }
                    ]
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated provider",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provider"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "providers"
        ],
        "summary": "Disable a provider",
        "description": "Soft-disables the provider; answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/providerId"
          }
        ],
        "responses": {
          "204": {
            "description": "Provider disabled"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/providers/{id}/health": {
      "get": {
        "tags": [
          "providers"
        ],
        "summary": "Probe a provider",
        "description": "Always answers 200 for a known provider; the status field reports ok / degraded / down.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/providerId"
          }
        ],
        "responses": {
          "200": {
            "description": "Provider health",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderHealth"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "List models",
        "description": "OpenAI-compatible model list. Bearer key sees only models its workspace/global providers serve; session sees all accessible models. Cursor paginated.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "provider",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by provider id (`provider_id` accepted as an alias)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of models with `object: list`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "models"
        ],
        "summary": "Price a model on a provider",
        "description": "Requires admin role of the organization owning the provider.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "provider_id"
                ],
                "properties": {
                  "provider_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "upstream_id": {
                    "type": "string"
                  },
                  "display_name": {
                    "type": "string"
                  },
                  "price_in": {
                    "type": "number",
                    "format": "double",
                    "description": "USD per 1M prompt tokens"
                  },
                  "price_out": {
                    "type": "number",
                    "format": "double",
                    "description": "USD per 1M completion tokens"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Model created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/models/{id}": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "Get a model",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/modelId"
          }
        ],
        "responses": {
          "200": {
            "description": "Model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/models/{id}/routes": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "List a model's fallback routes",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/modelId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered fallback chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelRoute"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "models"
        ],
        "summary": "Upsert a fallback route",
        "description": "Adds or updates a position in the model's fallback chain; target must be a model the caller may administer.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/modelId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_model_id"
                ],
                "properties": {
                  "target_model_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "position": {
                    "type": "integer",
                    "minimum": 0,
                    "default": 0
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Route upserted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelRoute"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/models/{id}/routes/{routeID}": {
      "delete": {
        "tags": [
          "models"
        ],
        "summary": "Delete a fallback route",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/modelId"
          },
          {
            "$ref": "#/components/parameters/routeId"
          }
        ],
        "responses": {
          "200": {
            "description": "Route deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "deleted"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "chat"
        ],
        "summary": "Chat completion",
        "description": "OpenAI-compatible chat completion. Authenticated with a workspace API\nkey (`Authorization: Bearer`). With `stream: false` (default) the\nresponse is a single JSON completion object. With `stream: true` the\nresponse is `text/event-stream`: each event is `data: <ChatChunk JSON>`\nfollowed by a blank line; the stream ends with `data: [DONE]`.\nUpstream failures mid-stream surface as `provider_error`; usage is\nbilled against the model that actually served the request.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion (JSON) or SSE stream of ChatChunk events ending in `data: [DONE]`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE stream of `data: <ChatChunk>` lines terminated by `data: [DONE]`"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Budget exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "budget_exceeded",
                    "message": "budget exceeded",
                    "type": "permission_error"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream provider error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Billing ledger unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "tags": [
          "chat"
        ],
        "summary": "Embeddings",
        "description": "OpenAI-compatible embeddings call for a single string or a list of strings. Bearer API key auth.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {
                    "description": "A single string or an array of strings",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding list with usage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "enum": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "object": {
                            "type": "string"
                          },
                          "embedding": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          },
                          "index": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "usage": {
                      "$ref": "#/components/schemas/Usage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Budget exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream provider error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Billing ledger unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "usage"
        ],
        "summary": "Usage summary",
        "description": "All-time totals plus breakdowns. Scope by `workspace_id` or `key_id` (key_id wins); `model`, `from`, `to` filter; `group_by` selects the breakdown dimension (key|model|day), omitted reports all.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "model",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "RFC3339 or YYYY-MM-DD; defaults to the whole ledger"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "RFC3339 or YYYY-MM-DD; defaults to now (period is [from, to))"
          },
          {
            "name": "group_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "key",
                "model",
                "day"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageSummary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/usage/events": {
      "get": {
        "tags": [
          "usage"
        ],
        "summary": "Usage events",
        "description": "Raw ledger events, newest first, cursor paginated. Same scope and filters as /v1/usage.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "model",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of usage events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageEventPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/usage/export.csv": {
      "get": {
        "tags": [
          "usage"
        ],
        "summary": "Export usage as CSV",
        "description": "Streams usage rows as CSV. `from`/`to` default to the current month; same scope and filters as /v1/usage.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "model",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV download",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/budgets": {
      "get": {
        "tags": [
          "budgets"
        ],
        "summary": "List budgets",
        "description": "Budget state of the scoped keys (`workspace_id` or `key_id`; without either, the caller's own organizations). Cursor paginated.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of budgets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BudgetPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "budgets"
        ],
        "summary": "Set a key's budget",
        "description": "Upserts the spend limit of a key. Requires admin role of the owning org.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "api_key_id",
                  "limit_usd"
                ],
                "properties": {
                  "api_key_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "limit_usd": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "period": {
                    "type": "string",
                    "default": "monthly"
                  },
                  "rpm_limit": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Budget created/updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Budget"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/budgets/{id}": {
      "patch": {
        "tags": [
          "budgets"
        ],
        "summary": "Update a budget",
        "description": "Changes the spend limit (and optionally the key's rpm_limit); spend and period end are preserved.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/budgetId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit_usd": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "rpm_limit": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated budget",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Budget"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/billing/plans": {
      "get": {
        "tags": [
          "billing"
        ],
        "summary": "List billing plans",
        "description": "Plan catalog. Optional `currency` query parameter (defaults to the deployment currency).",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plan catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BillingPlan"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/billing/subscription": {
      "get": {
        "tags": [
          "billing"
        ],
        "summary": "Get the organization subscription",
        "description": "Optional `org_id` query parameter; defaults to the caller's first owned organization.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "org_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription (implicit free plan when none exists)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/billing/checkout-session": {
      "post": {
        "tags": [
          "billing"
        ],
        "summary": "Create a Stripe checkout session",
        "description": "Requires the billing role of the organization.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "org_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string"
                  },
                  "mode": {
                    "type": "string"
                  },
                  "interval": {
                    "type": "string"
                  },
                  "success_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "cancel_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "payment_methods": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/billing/portal-session": {
      "post": {
        "tags": [
          "billing"
        ],
        "summary": "Create a Stripe billing portal session",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "org_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "return_url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Portal session URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/billing/invoices": {
      "get": {
        "tags": [
          "billing"
        ],
        "summary": "List invoices",
        "description": "Optional `org_id`, `status` (draft|open|paid|void|uncollectible), `limit`, `cursor`.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "org_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "open",
                "paid",
                "void",
                "uncollectible"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of invoices",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoicePage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "webhooks"
        ],
        "summary": "List webhook subscriptions",
        "description": "Subscriptions of one workspace. `workspace_id` is required. The signing secret is never returned; only `secret_prefix`.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriptions of the workspace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "Create a webhook subscription",
        "description": "Registers a URL the core POSTs signed event envelopes to. Requires admin role of the owning org. Events: `usage.threshold` (50%/80% of the workspace's monthly budget), `usage.milestone` ($25/$50/$100/$250/$500/$1000 cumulative monthly spend), `budget.exceeded` (spend reaches the limit), `webhook.test`. URL must be https (http only for localhost) and pass the SSRF policy. The `secret` (`whsec_...`) is returned once in this response only.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspace_id",
                  "url",
                  "events"
                ],
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "url": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "usage.threshold",
                        "usage.milestone",
                        "budget.exceeded",
                        "webhook.test"
                      ]
                    }
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created; `secret` is returned once",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    },
                    "secret": {
                      "type": "string",
                      "description": "HMAC signing secret, shown once"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "patch": {
        "tags": [
          "webhooks"
        ],
        "summary": "Update a webhook subscription",
        "description": "Changes url, events and/or enabled. Requires admin role of the owning org.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "usage.threshold",
                        "usage.milestone",
                        "budget.exceeded",
                        "webhook.test"
                      ]
                    }
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated subscription",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "webhooks"
        ],
        "summary": "Delete a webhook subscription",
        "description": "Removes the subscription and its delivery history. Requires admin role of the owning org.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "Send a test event",
        "description": "Delivers a `webhook.test` envelope synchronously (same signing and retry path as real events) and reports the outcome. Answers 502 when the receiver did not accept the event.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test delivery accepted by the receiver",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "delivered",
                            "failed"
                          ]
                        },
                        "status_code": {
                          "type": "integer"
                        },
                        "attempts": {
                          "type": "integer"
                        },
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "description": "Receiver did not accept the test event",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "status_code": {
                          "type": "integer"
                        },
                        "attempts": {
                          "type": "integer"
                        },
                        "error": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/stripe": {
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "Stripe webhook receiver",
        "description": "Anonymous; authenticated by the `Stripe-Signature` header. Verified, deduplicated by event id, then applied. Answers `{\"received\": true}`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Stripe-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event acknowledged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "received": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/SecretsUnavailable"
          }
        }
      }
    },
    "/v1/plugins": {
      "get": {
        "tags": [
          "plugins"
        ],
        "summary": "List installed plugins",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pagination"
          }
        ],
        "responses": {
          "200": {
            "description": "Page of plugins",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/plugins/install": {
      "post": {
        "tags": [
          "plugins"
        ],
        "summary": "Install a plugin",
        "description": "Deployment owner only.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "ring": {
                    "type": "integer"
                  },
                  "config": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plugin installed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plugin"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/plugins/{id}": {
      "patch": {
        "tags": [
          "plugins"
        ],
        "summary": "Update a plugin",
        "description": "Toggle enabled and/or ring. Deployment owner only.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pluginId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "ring": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated plugin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plugin"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "plugins"
        ],
        "summary": "Remove a plugin",
        "description": "Deployment owner only; answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pluginId"
          }
        ],
        "responses": {
          "204": {
            "description": "Plugin removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/plugins/{id}/config": {
      "get": {
        "tags": [
          "plugins"
        ],
        "summary": "Get a plugin's configuration",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pluginId"
          }
        ],
        "responses": {
          "200": {
            "description": "Plugin configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "plugins"
        ],
        "summary": "Update a plugin's configuration",
        "description": "Deployment owner only.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pluginId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "config"
                ],
                "properties": {
                  "config": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/ai/configs": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "List AI configurations",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Page of AI configs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AIConfig"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "ai"
        ],
        "summary": "Create an AI configuration from a natural language prompt",
        "description": "The config engine parses the prompt and derives models/providers.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "prompt"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "default_model": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "AI config created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/ai/configs/{id}": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "Get an AI configuration",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "200": {
            "description": "AI config",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "ai"
        ],
        "summary": "Update an AI configuration",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "default_model": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated AI config",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "ai"
        ],
        "summary": "Delete an AI configuration",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "204": {
            "description": "AI config removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/ai/skills": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "List AI skills",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Page of AI skills",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AISkill"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "ai"
        ],
        "summary": "Create an AI skill",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "AI skill created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AISkill"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/ai/skills/{id}": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "Get an AI skill",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "200": {
            "description": "AI skill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AISkill"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "ai"
        ],
        "summary": "Update an AI skill",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated AI skill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AISkill"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "ai"
        ],
        "summary": "Delete an AI skill",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "204": {
            "description": "AI skill removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/ai/agents": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "List AI agents",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Page of AI agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AIAgent"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "ai"
        ],
        "summary": "Create an AI agent",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "model": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "AI agent created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIAgent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/ai/agents/{id}": {
      "get": {
        "tags": [
          "ai"
        ],
        "summary": "Get an AI agent",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "200": {
            "description": "AI agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIAgent"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "ai"
        ],
        "summary": "Update an AI agent",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "model": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated AI agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AIAgent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "ai"
        ],
        "summary": "Delete an AI agent",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/aiId"
          }
        ],
        "responses": {
          "204": {
            "description": "AI agent removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/consumers": {
      "get": {
        "tags": [
          "consumers"
        ],
        "summary": "List consumers",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Page of consumers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Consumer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "consumers"
        ],
        "summary": "Create a consumer",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "payg",
                      "pro",
                      "business",
                      "enterprise"
                    ]
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Consumer created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consumer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/consumers/{id}": {
      "get": {
        "tags": [
          "consumers"
        ],
        "summary": "Get a consumer",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/consumerId"
          }
        ],
        "responses": {
          "200": {
            "description": "Consumer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consumer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "consumers"
        ],
        "summary": "Update a consumer",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/consumerId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "payg",
                      "pro",
                      "business",
                      "enterprise"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "suspended",
                      "archived"
                    ]
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated consumer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consumer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "consumers"
        ],
        "summary": "Delete a consumer",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/consumerId"
          }
        ],
        "responses": {
          "204": {
            "description": "Consumer removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/users": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "List users",
        "description": "Deployment admin only. Cursor paginated.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pagination"
          }
        ],
        "responses": {
          "200": {
            "description": "Page of users",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "admin"
        ],
        "summary": "Create a user",
        "description": "Creates an invited account; an activation token is emailed via the invite notifier when send_invite is true (default).",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "role"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "billing"
                    ]
                  },
                  "send_invite": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/admin/users/{id}": {
      "patch": {
        "tags": [
          "admin"
        ],
        "summary": "Update a user",
        "description": "Whitelisted to `role` and `status` (active|invited|suspended). Guards against privilege escalation and self-modification.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/userId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "billing"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "invited",
                      "suspended"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "admin"
        ],
        "summary": "Soft-delete a user",
        "description": "Revokes the user's sessions; answers 204.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/userId"
          }
        ],
        "responses": {
          "204": {
            "description": "User deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/audit-log": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "Audit log",
        "description": "Filters `actor`, `action`, `from`, `to`; keyset paginated.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "actor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of audit events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/system": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "System status",
        "description": "Version, uptime, Go version and honest db/redis status.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "System status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "uptime_seconds": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "go_version": {
                      "type": "string"
                    },
                    "db_status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "fail",
                        "unavailable"
                      ]
                    },
                    "redis_status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "fail",
                        "unavailable"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/models/pricing": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "Model pricing views",
        "description": "Default/recommended/effective prices per model plus cheapest alternative.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Pricing views",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelPricingView"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/models/{id}/pricing": {
      "patch": {
        "tags": [
          "admin"
        ],
        "summary": "Update model pricing",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/modelId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt_per_1m": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "completion_per_1m": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0
                  },
                  "price_source": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated pricing view",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelPricingView"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/price-policies": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "List price policies",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Price policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PricePolicy"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "admin"
        ],
        "summary": "Create/upsert a price policy",
        "description": "One rule per scope; margin_pct 0-1000.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope_type": {
                    "type": "string",
                    "enum": [
                      "global",
                      "provider",
                      "org",
                      "workspace",
                      "plan",
                      "model"
                    ],
                    "default": "global"
                  },
                  "scope_ref": {
                    "type": "string"
                  },
                  "margin_pct": {
                    "type": "number",
                    "format": "double",
                    "minimum": 0,
                    "maximum": 1000
                  },
                  "note": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Policy upserted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricePolicy"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/price-policies/{id}": {
      "delete": {
        "tags": [
          "admin"
        ],
        "summary": "Delete a price policy",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/pricePolicyId"
          }
        ],
        "responses": {
          "204": {
            "description": "Policy deleted"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/notifications": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "List notifications",
        "description": "Optional `status` filter: open|applied|dismissed.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "applied",
                "dismissed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notifications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Notification"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/notifications/{id}": {
      "patch": {
        "tags": [
          "admin"
        ],
        "summary": "Resolve a notification",
        "description": "status must be `applied` or `dismissed`.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/notificationId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "applied",
                      "dismissed"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated notification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/feeds": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "List provider feeds",
        "description": "Optional `enabled=true` filter.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "enabled",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Feeds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Feed"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "admin"
        ],
        "summary": "Create/upsert a provider feed",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "adapter",
                  "label"
                ],
                "properties": {
                  "adapter": {
                    "type": "string",
                    "enum": [
                      "openrouter",
                      "provider_api",
                      "static_file"
                    ]
                  },
                  "label": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object"
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Feed upserted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Feed"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/admin/feeds/{id}": {
      "get": {
        "tags": [
          "admin"
        ],
        "summary": "Get a provider feed",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/feedId"
          }
        ],
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Feed"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/admin/feeds/{id}/run": {
      "post": {
        "tags": [
          "admin"
        ],
        "summary": "Run a feed synchronously",
        "description": "Executes the discovery comparison and returns the count of notifications created.",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/feedId"
          }
        ],
        "responses": {
          "200": {
            "description": "Feed run result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "feed_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "notifications_created": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/healthz": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Liveness probe",
        "description": "Public; reports status, version and uptime.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "version": {
                      "type": "string"
                    },
                    "uptime_seconds": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/version": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Build info",
        "description": "Public; reports version, commit and build time.",
        "security": [],
        "responses": {
          "200": {
            "description": "Build info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "commit": {
                      "type": "string"
                    },
                    "build_time": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Readiness probe",
        "description": "Public; served by the healthz plugin — 200 `{\"status\":\"ready\"}` once started, 503 `{\"status\":\"starting\"}` before.",
        "security": [],
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ready"
                      ]
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Starting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "starting"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Prometheus metrics",
        "description": "Operational counters in Prometheus text exposition format. Requires a session or the service token (`Authorization: Bearer` or `X-Service-Token`).",
        "security": [
          {
            "sessionCookie": []
          },
          {
            "bearerAuth": []
          },
          {
            "serviceToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Metrics exposition",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "This OpenAPI document",
        "description": "Public; serves the spec itself as JSON.",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "aetherin_session",
        "description": "Session cookie set by POST /v1/auth/login"
      },
      "csrfToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CSRF-Token",
        "description": "Session CSRF token required on mutations authorized by the cookie"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Workspace API key (`ak_...`) for the data plane"
      },
      "serviceToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Service-Token",
        "description": "Service-to-service token for scraping /metrics"
      }
    },
    "parameters": {
      "orgId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "workspaceId": {
        "name": "workspaceId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "keyId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "modelId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "routeId": {
        "name": "routeID",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "memberId": {
        "name": "memberId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "inviteId": {
        "name": "inviteId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "budgetId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "pluginId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "providerId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "userId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "pricePolicyId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "notificationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "aiId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "consumerId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "feedId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "pagination": [
        {
          "name": "limit",
          "in": "query",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        {
          "name": "cursor",
          "in": "query",
          "schema": {
            "type": "string"
          }
        }
      ]
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication required or failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Permission denied for this resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "CSRFInvalid": {
        "description": "Missing or stale CSRF token (`error.code` = csrf_invalid)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "State conflict (duplicate, already exists, no longer pending)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "Request understood but failed to process (e.g. feed run error)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "SecretsUnavailable": {
        "description": "Billing/secrets not configured (error.code = secrets_unavailable)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "type"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine code",
                "e.g. invalid_request": null,
                "unauthorized": null,
                "forbidden": null,
                "not_found": null,
                "conflict": null,
                "csrf_invalid": null,
                "rate_limit_exceeded": null,
                "budget_exceeded": null,
                "provider_error": null,
                "internal_error": null,
                "secrets_unavailable": null
              },
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "description": "Coarse category derived from the code"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "AIConfig": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "models",
          "default_model",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "default_model": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AISkill": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AIAgent": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Consumer": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "plan",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended",
              "archived"
            ]
          },
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "payg",
              "pro",
              "business",
              "enterprise"
            ]
          },
          "metadata": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Timestamp": {
        "type": "string",
        "format": "date-time"
      },
      "AuthUser": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "billing"
            ]
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "billing"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "invited",
              "suspended",
              "deleted"
            ]
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Org": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "billing"
            ]
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Invite": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "billing"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "expired",
              "revoked"
            ]
          },
          "invited_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "expires_at": {
            "$ref": "#/components/schemas/Timestamp",
            "nullable": true
          },
          "accepted_at": {
            "$ref": "#/components/schemas/Timestamp",
            "nullable": true
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "InviteCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Invite"
          },
          {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "description": "One-time bearer token",
                "shown once": null
              },
              "accept_url": {
                "type": "string"
              }
            }
          }
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "budget_usd_monthly": {
            "type": "number",
            "format": "double"
          },
          "rpm_limit": {
            "type": "integer"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "revoked_at": {
            "$ref": "#/components/schemas/Timestamp",
            "nullable": true
          }
        }
      },
      "ApiKeyCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiKey"
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "description": "Plaintext API key",
                "shown exactly once": null
              }
            }
          }
        ]
      },
      "ModelPricing": {
        "type": "object",
        "properties": {
          "prompt_per_1m": {
            "type": "number",
            "format": "double"
          },
          "completion_per_1m": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "model"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_id": {
            "type": "string",
            "format": "uuid"
          },
          "upstream_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "pricing": {
            "$ref": "#/components/schemas/ModelPricing"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "ModelRoute": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "type": "string",
            "format": "uuid"
          },
          "target_model_id": {
            "type": "string",
            "format": "uuid"
          },
          "position": {
            "type": "integer"
          },
          "enabled": {
            "type": "boolean"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Provider": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "null = deployment-global"
          },
          "type": {
            "type": "string"
          },
          "base_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "enabled": {
            "type": "boolean"
          },
          "source": {
            "type": "string"
          },
          "has_credentials": {
            "type": "boolean"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "ProviderHealth": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ]
          },
          "latency_ms": {
            "type": "integer",
            "format": "int64"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Plugin": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "ring": {
            "type": "integer"
          },
          "enabled": {
            "type": "boolean"
          },
          "config_json": {
            "type": "object"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "PluginConfig": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      },
      "UsageTotals": {
        "type": "object",
        "properties": {
          "requests": {
            "type": "integer"
          },
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "UsageBreakdown": {
        "type": "object",
        "properties": {
          "key_id": {
            "type": "string",
            "format": "uuid"
          },
          "model": {
            "type": "string"
          },
          "model_id": {
            "type": "string",
            "format": "uuid"
          },
          "day": {
            "type": "string",
            "format": "date"
          },
          "requests": {
            "type": "integer"
          },
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "UsageSummary": {
        "type": "object",
        "properties": {
          "totals": {
            "$ref": "#/components/schemas/UsageTotals"
          },
          "by_key": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageBreakdown"
            }
          },
          "by_model": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageBreakdown"
            }
          },
          "by_day": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageBreakdown"
            }
          }
        }
      },
      "UsageEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "api_key_id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "type": "string",
            "format": "uuid"
          },
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number",
            "format": "double"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Budget": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "api_key_id": {
            "type": "string",
            "format": "uuid"
          },
          "period": {
            "type": "string",
            "example": "monthly"
          },
          "limit_usd": {
            "type": "number",
            "format": "double"
          },
          "spent_usd": {
            "type": "number",
            "format": "double"
          },
          "reset_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "usage.threshold",
                "usage.milestone",
                "budget.exceeded",
                "webhook.test"
              ]
            }
          },
          "secret_prefix": {
            "type": "string",
            "description": "First characters of the signing secret; the full secret is returned once at creation"
          },
          "enabled": {
            "type": "boolean"
          },
          "last_delivery_at": {
            "$ref": "#/components/schemas/Timestamp",
            "nullable": true
          },
          "last_delivery_status": {
            "type": "string",
            "enum": [
              "delivered",
              "failed"
            ]
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "updated_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "BillingPlan": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "interval": {
            "type": "string"
          },
          "unit_amount": {
            "type": "number",
            "format": "double"
          },
          "included_requests": {
            "type": "integer",
            "format": "int64"
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "plan": {
            "type": "string"
          },
          "interval": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "seats": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "payment_method": {
            "type": "string",
            "nullable": true
          },
          "current_period_start": {
            "type": "string",
            "format": "date-time"
          },
          "current_period_end": {
            "type": "string",
            "format": "date-time"
          },
          "cancel_at_period_end": {
            "type": "boolean"
          },
          "trial_end": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "stripe_customer_id": {
            "type": "string",
            "nullable": true
          },
          "stripe_subscription_id": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "number": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "open",
              "paid",
              "void",
              "uncollectible"
            ]
          },
          "currency": {
            "type": "string"
          },
          "subtotal": {
            "type": "number",
            "format": "double"
          },
          "tax": {
            "type": "number",
            "format": "double"
          },
          "total": {
            "type": "number",
            "format": "double"
          },
          "amount_due": {
            "type": "number",
            "format": "double"
          },
          "amount_paid": {
            "type": "number",
            "format": "double"
          },
          "hosted_invoice_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "invoice_pdf": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "period_start": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "period_end": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CheckoutSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "interval": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PortalSession": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "AuditEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "actor": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "target": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "PricePolicy": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "scope_type": {
            "type": "string",
            "enum": [
              "global",
              "provider",
              "org",
              "workspace",
              "plan",
              "model"
            ]
          },
          "scope_ref": {
            "type": "string"
          },
          "margin_pct": {
            "type": "number",
            "format": "double"
          },
          "note": {},
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "updated_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "payload": {
            "type": "object"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "applied",
              "dismissed"
            ]
          },
          "source_feed": {
            "nullable": true
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Feed": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "adapter": {
            "type": "string",
            "enum": [
              "openrouter",
              "provider_api",
              "static_file"
            ]
          },
          "label": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "enabled": {
            "type": "boolean"
          },
          "last_run_at": {
            "nullable": true,
            "description": "RFC3339 string or null"
          },
          "last_status": {
            "nullable": true
          },
          "last_detail": {
            "nullable": true
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "Per1M": {
        "type": "object",
        "properties": {
          "prompt_per_1m": {
            "type": "number",
            "format": "double"
          },
          "completion_per_1m": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "ModelPricingView": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider": {
            "type": "string"
          },
          "upstream_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "prices": {
            "type": "object",
            "properties": {
              "default": {
                "$ref": "#/components/schemas/Per1M"
              },
              "recommended": {
                "$ref": "#/components/schemas/Per1M"
              },
              "effective": {
                "$ref": "#/components/schemas/Per1M"
              }
            }
          },
          "margin_pct": {
            "type": "number",
            "format": "double"
          },
          "price_source": {
            "type": "string",
            "nullable": true
          },
          "price_verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "cheapest_alternative": {
            "type": "object",
            "nullable": true,
            "properties": {
              "model_id": {
                "type": "string",
                "format": "uuid"
              },
              "provider": {
                "type": "string"
              },
              "pricing": {
                "$ref": "#/components/schemas/Per1M"
              },
              "delta_pct": {
                "type": "number",
                "format": "double"
              }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tool_call_id": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "function": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "arguments": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model id or upstream_id"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "max_tokens": {
            "type": "integer"
          },
          "temperature": {
            "type": "number",
            "format": "double"
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean"
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {}
          },
          "tool_choice": {}
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "enum": [
              "chat.completion"
            ]
          },
          "created": {
            "type": "integer",
            "format": "int64"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "ChatChunk": {
        "type": "object",
        "description": "One SSE `data:` payload when stream=true",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "created": {
            "type": "integer",
            "format": "int64"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "delta": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string"
                    },
                    "content": {
                      "type": "string",
                      "nullable": true
                    },
                    "tool_calls": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string"
                          },
                          "function": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "arguments": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "finish_reason": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "OrgPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Org"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "WorkspacePage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workspace"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "MemberPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "InvitePage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invite"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ApiKeyPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKey"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ProviderPage": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Provider"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ModelListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PluginPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Plugin"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "UserPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AuditEventPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "BudgetPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Budget"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "InvoicePage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "UsageEventPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageEvent"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  }
}