{
  "openapi": "3.0.3",
  "info": {
    "title": "The Overseer Public API",
    "version": "1.0.0",
    "description": "Read-only access to a Discord server's XP leaderboard, rank ladder, member standings and who is live on Twitch. Part of the Ultimate plan. Authenticate with the server's API key (made in the dashboard under Public API) in the Authorization header. Call it from a backend or serverless function, never from browser code: no CORS headers are sent. Limit: 60 requests per minute per server; data refreshes about once a minute, so cache results for a minute or two. Docs: https://mavops.org/docs/api"
  },
  "servers": [{ "url": "https://dash.mavops.org/api/public/v1" }],
  "security": [{ "ApiKey": [] }],
  "paths": {
    "/guilds/{guildId}/leaderboard": {
      "get": {
        "operationId": "getLeaderboard",
        "summary": "XP leaderboard, best first",
        "description": "Members with XP greater than 0, best first. Equal XP shares a position. Members who left the server are not listed.",
        "parameters": [
          { "$ref": "#/components/parameters/GuildId" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "How many members to return." },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "How many members to skip (for paging)." }
        ],
        "responses": {
          "200": { "description": "The leaderboard page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/guilds/{guildId}/ranks": {
      "get": {
        "operationId": "getRanks",
        "summary": "The rank ladder",
        "description": "Ranks from Unranked upward with the XP each one needs, as configured for the server.",
        "parameters": [{ "$ref": "#/components/parameters/GuildId" }],
        "responses": {
          "200": { "description": "The rank ladder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ranks" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/guilds/{guildId}/live": {
      "get": {
        "operationId": "getLive",
        "summary": "Who is live on Twitch right now",
        "description": "Members who linked their Twitch account in this server (with /linktwitch) and are live, busiest first. Refreshed about every 5 minutes, so a stream can take a few minutes to appear or disappear. Members without a linked account and streams announced only through extra channels are not included. An empty list means nobody is live.",
        "parameters": [{ "$ref": "#/components/parameters/GuildId" }],
        "responses": {
          "200": { "description": "The live list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Live" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/guilds/{guildId}/members/{userId}": {
      "get": {
        "operationId": "getMember",
        "summary": "One member's standing",
        "description": "Position, XP, level and rank for one member, plus how much XP the next rank needs (nextRank is null at the top rank). 404 if the member has no XP in the server yet.",
        "parameters": [
          { "$ref": "#/components/parameters/GuildId" },
          { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{15,25}$" }, "description": "The member's Discord user ID." }
        ],
        "responses": {
          "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "http", "scheme": "bearer", "description": "The server's API key, starting with mvo_live_. Sent as: Authorization: Bearer <key>." }
    },
    "parameters": {
      "GuildId": { "name": "guildId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Discord server ID. Must be the server the API key belongs to, otherwise 403 wrong_server." }
    },
    "responses": {
      "Error": { "description": "An error. error is a stable code: missing_key, invalid_key (401); wrong_server, plan_required (403); bad_user_id (400); member_not_found (404); server_error (500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "More than 60 requests in a minute. Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string", "example": "invalid_key" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } },
        "required": ["error", "message"]
      },
      "Rank": {
        "type": "object",
        "properties": { "key": { "type": "string", "example": "gold" }, "name": { "type": "string", "example": "Gold" } },
        "required": ["key", "name"]
      },
      "Member": {
        "type": "object",
        "properties": {
          "position": { "type": "integer", "nullable": true, "description": "Leaderboard position (1 is best). Null when the member has 0 XP." },
          "userId": { "type": "string" },
          "username": { "type": "string", "description": "The member's current server display name." },
          "avatarUrl": { "type": "string", "nullable": true },
          "xp": { "type": "integer" },
          "level": { "type": "integer" },
          "rank": { "$ref": "#/components/schemas/Rank" },
          "lastActive": { "type": "string", "nullable": true, "format": "date-time" }
        },
        "required": ["position", "userId", "username", "xp", "level", "rank"]
      },
      "Leaderboard": {
        "type": "object",
        "properties": {
          "guildId": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "total": { "type": "integer", "description": "How many members have XP in total (use with limit and offset to page)." },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }
        },
        "required": ["guildId", "updatedAt", "total", "limit", "offset", "members"]
      },
      "Ranks": {
        "type": "object",
        "properties": {
          "guildId": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "ranks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "xp": { "type": "integer", "description": "XP needed to reach this rank." } },
              "required": ["key", "name", "xp"]
            }
          }
        },
        "required": ["guildId", "updatedAt", "ranks"]
      },
      "Live": {
        "type": "object",
        "properties": {
          "guildId": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "total": { "type": "integer" },
          "live": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "userId": { "type": "string" },
                "username": { "type": "string" },
                "avatarUrl": { "type": "string", "nullable": true },
                "platform": { "type": "string", "example": "twitch" },
                "login": { "type": "string", "description": "Twitch channel name." },
                "url": { "type": "string", "example": "https://www.twitch.tv/alice_tv" },
                "title": { "type": "string", "nullable": true },
                "game": { "type": "string", "nullable": true },
                "viewers": { "type": "integer", "nullable": true },
                "startedAt": { "type": "string", "nullable": true, "format": "date-time" }
              },
              "required": ["userId", "username", "platform", "login", "url"]
            }
          }
        },
        "required": ["guildId", "updatedAt", "total", "live"]
      },
      "MemberResponse": {
        "type": "object",
        "properties": {
          "guildId": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "member": {
            "allOf": [
              { "$ref": "#/components/schemas/Member" },
              {
                "type": "object",
                "properties": {
                  "nextRank": {
                    "type": "object",
                    "nullable": true,
                    "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "xpNeeded": { "type": "integer", "description": "XP still needed to reach it." } }
                  }
                }
              }
            ]
          }
        },
        "required": ["guildId", "updatedAt", "member"]
      }
    }
  }
}
