{
  "openapi": "3.1.0",
  "info": {
    "title": "ARCANA Site API",
    "version": "1.0.0",
    "description": "Public and authenticated HTTP endpoints exposed by arcana.otnelhq.com. ARCANA uses this small site API for status, feedback, account/session surfaces, billing helpers, and CLI device-flow account discovery."
  },
  "servers": [
    { "url": "https://arcana.otnelhq.com", "description": "ARCANA production" }
  ],
  "tags": [
    { "name": "Public", "description": "Endpoints callable without an ARCANA bearer credential." },
    { "name": "Account", "description": "Authenticated account and workspace endpoints." },
    { "name": "Billing", "description": "Billing and subscription helper endpoints." }
  ],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getArcanaServiceStatus",
        "summary": "Get ARCANA service status",
        "description": "Checks the public ARCANA website and dependent services and returns a machine-readable availability summary.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Current service status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" }
              }
            }
          }
        }
      }
    },
    "/api/feedback": {
      "get": {
        "operationId": "listPublicFeedback",
        "summary": "List public ARCANA feedback",
        "description": "Returns approved public feedback entries, newest first.",
        "tags": ["Public"],
        "responses": {
          "200": {
            "description": "Approved public feedback.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Feedback" }
                    }
                  },
                  "required": ["reviews"]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "submitPublicFeedback",
        "summary": "Submit ARCANA feedback",
        "description": "Submits a review. Submissions are rate-limited and lower-star reviews may require moderation.",
        "tags": ["Public"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FeedbackInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback accepted.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } }
          },
          "400": {
            "description": "Invalid feedback payload.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "429": {
            "description": "Submission rate limit reached.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/api/user": {
      "get": {
        "operationId": "getAuthenticatedUser",
        "summary": "Resolve the authenticated ARCANA user",
        "description": "Validates the bearer credential and returns the identity used by ARCANA CLI account discovery.",
        "tags": ["Account"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Authenticated user identity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "email": { "type": "string" }
                  },
                  "required": ["id", "email"]
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing or invalid.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/api/orgs": {
      "get": {
        "operationId": "listAuthenticatedOrganizations",
        "summary": "List ARCANA workspaces for the authenticated user",
        "description": "Returns the organization/workspace list used by the CLI after device-flow login.",
        "tags": ["Account"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Available workspaces.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "name": { "type": "string" }
                    },
                    "required": ["id", "name"]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing or invalid.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/api/profile": {
      "get": {
        "operationId": "getArcanaProfile",
        "summary": "Get the authenticated ARCANA profile",
        "description": "Returns profile data from the ARCANA proxy for the bearer credential.",
        "tags": ["Account"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Profile JSON returned by the upstream ARCANA service.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "401": { "description": "Bearer credential missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Upstream service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      },
      "put": {
        "operationId": "updateArcanaProfile",
        "summary": "Update the authenticated ARCANA profile",
        "description": "Forwards a JSON profile update to the ARCANA proxy.",
        "tags": ["Account"],
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
        },
        "responses": {
          "200": { "description": "Updated profile JSON.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "401": { "description": "Bearer credential missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Upstream service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/sessions": {
      "get": {
        "operationId": "listArcanaSessions",
        "summary": "List authenticated ARCANA sessions",
        "description": "Forwards the request query string to the ARCANA session service and returns its JSON response.",
        "tags": ["Account"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Session data from the ARCANA service.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "401": { "description": "Bearer credential missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Upstream service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/billing": {
      "get": {
        "operationId": "getArcanaBilling",
        "summary": "Get authenticated ARCANA billing data",
        "description": "Returns purchases, or a subscription status when the sub query parameter is supplied.",
        "tags": ["Billing"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "sub",
            "in": "query",
            "required": false,
            "description": "Subscription identifier. When present, returns that subscription's status instead of the purchase list.",
            "schema": { "type": "string", "minLength": 1 }
          }
        ],
        "responses": {
          "200": { "description": "Billing data from the ARCANA service.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "401": { "description": "Bearer credential missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Upstream service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/create-sub": {
      "post": {
        "operationId": "createArcanaSubscription",
        "summary": "Create an ARCANA subscription checkout",
        "description": "Forwards a subscription creation payload to ARCANA's billing service and returns its JSON result.",
        "tags": ["Billing"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
        },
        "responses": {
          "200": { "description": "Subscription creation result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "400": { "description": "Invalid subscription request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Subscription service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "ARCANA bearer credential obtained through the documented authentication flow."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Stable machine-readable error code." },
          "message": { "type": "string", "description": "Human-readable explanation when available." },
          "resolution": { "type": "string", "description": "A recovery hint when the server can provide one." }
        },
        "required": ["error"]
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "message": { "type": "string" }
        },
        "required": ["ok"]
      },
      "Feedback": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "stars": { "type": "integer", "minimum": 1, "maximum": 5 },
          "message": { "type": "string" },
          "created_at": { "type": "string" }
        },
        "required": ["id", "name", "stars", "message", "created_at"]
      },
      "FeedbackInput": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "maxLength": 60 },
          "stars": { "type": "integer", "minimum": 1, "maximum": 5 },
          "message": { "type": "string", "minLength": 1, "maxLength": 500 }
        },
        "required": ["stars", "message"]
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "lastChecked": { "type": "string", "format": "date-time" },
          "summary": { "type": "string", "enum": ["operational", "issues"] },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "status": { "type": "string", "enum": ["up", "down"] },
                "latency": { "type": "integer", "minimum": 0 },
                "error": { "type": "string" }
              },
              "required": ["name", "status", "latency"]
            }
          }
        },
        "required": ["lastChecked", "services", "summary"]
      }
    }
  }
}