{
  "openapi": "3.1.0",
  "info": {
    "title": "Nola Public API",
    "version": "1.0.0",
    "description": "REST API for a single Nola provider account. Every request is scoped to the provider that owns the API key used to authenticate — there is no cross-provider access. Rate limit: 600 requests/minute per key."
  },
  "servers": [
    {
      "url": "https://<your-deployment>.convex.site",
      "description": "Your Convex deployment's HTTP actions host (see Convex dashboard → Settings → URL & Deploy Key; replace .convex.cloud with .convex.site)."
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Bookings" },
    { "name": "Availability" },
    { "name": "Resources" },
    { "name": "Clients" },
    { "name": "Wallet" }
  ],
  "paths": {
    "/api/v1/bookings": {
      "get": {
        "tags": ["Bookings"],
        "summary": "List bookings",
        "security": [{ "bearerAuth": ["bookings:read"] }],
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Start of range, ms since epoch." },
          { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "End of range, ms since epoch." },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "confirmed", "cancelled", "completed", "no_show"] } },
          { "name": "resourceId", "in": "query", "schema": { "type": "string" } },
          { "name": "cursor", "in": "query", "schema": { "type": "integer" }, "description": "Pass the previous response's nextCursor to page forward." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } },
                    "nextCursor": { "type": ["integer", "null"] }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Bookings"],
        "summary": "Create a booking",
        "security": [{ "bearerAuth": ["bookings:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["serviceId", "startMs"],
                "properties": {
                  "serviceId": { "type": "string" },
                  "startMs": { "type": "integer", "description": "Booking start time, ms since epoch." },
                  "resourceId": { "type": "string" },
                  "durationMinutes": { "type": "integer" },
                  "notes": { "type": "string" },
                  "clientId": { "type": "string", "description": "Existing client id. Omit to create/use a walk-in customer, or pass `client`." },
                  "client": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "email": { "type": "string" },
                      "phone": { "type": "string" }
                    },
                    "required": ["name"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/v1/bookings/{id}": {
      "delete": {
        "tags": ["Bookings"],
        "summary": "Cancel a booking",
        "security": [{ "bearerAuth": ["bookings:write"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } },
          "404": { "description": "Booking not found" }
        }
      }
    },
    "/api/v1/availability": {
      "get": {
        "tags": ["Availability"],
        "summary": "Get 30-minute availability slots for a day",
        "security": [{ "bearerAuth": ["availability:read"] }],
        "parameters": [
          { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD, interpreted as UTC midnight." },
          { "name": "resourceId", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "startMs": { "type": "integer" },
                          "endMs": { "type": "integer" },
                          "available": { "type": "boolean" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" }
        }
      }
    },
    "/api/v1/resources": {
      "get": {
        "tags": ["Resources"],
        "summary": "List active resources (courts, rooms, staff, equipment)",
        "security": [{ "bearerAuth": ["resources:read"] }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/clients": {
      "get": {
        "tags": ["Clients"],
        "summary": "List clients",
        "security": [{ "bearerAuth": ["clients:read"] }],
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } },
                    "nextCursor": { "type": ["integer", "null"] }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Clients"],
        "summary": "Create a client",
        "security": [{ "bearerAuth": ["clients:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string" },
                  "phone": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" }
        }
      }
    },
    "/api/v1/wallet/transactions": {
      "get": {
        "tags": ["Wallet"],
        "summary": "List wallet ledger transactions",
        "security": [{ "bearerAuth": ["wallet:read"] }],
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransaction" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "oh_live_<prefix>_<secret>",
        "description": "Create a key in Provider → API & webhooks. Scopes required per-endpoint are listed on each operation."
      }
    },
    "schemas": {
      "Booking": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "serviceId": { "type": "string" },
          "startMs": { "type": "integer" },
          "endMs": { "type": "integer" },
          "partySize": { "type": "integer" },
          "status": { "type": "string", "enum": ["pending", "confirmed", "cancelled", "completed", "no_show"] },
          "paymentStatus": { "type": "string" },
          "priceCents": { "type": "integer" },
          "currency": { "type": "string" },
          "notes": { "type": "string" },
          "createdAt": { "type": "integer" },
          "updatedAt": { "type": "integer" }
        }
      },
      "Resource": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "kind": { "type": "string" },
          "resourceType": { "type": "string" },
          "capacity": { "type": "integer" }
        }
      },
      "Client": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "createdAt": { "type": "integer" }
        }
      },
      "WalletTransaction": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" },
          "amountCents": { "type": "integer" },
          "currency": { "type": "string" },
          "description": { "type": "string" },
          "bookingId": { "type": "string" },
          "createdAt": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "Key is missing the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "UnprocessableEntity": { "description": "Invalid request body or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "More than 600 requests/minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}