{ "openapi": "3.0.0", "info": { "title": "Keystone.guru API", "version": "1" }, "paths": { "/api/v1/dungeon": { "get": { "tags": [ "Dungeon" ], "summary": "Get a list of dungeons", "operationId": "getDungeons", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DungeonEnvelope" } } } } } } }, "/api/v1/dungeon/{dungeon}": { "get": { "tags": [ "Dungeon" ], "summary": "Get the details of a specific dungeon", "operationId": "getDungeon", "parameters": [ { "name": "dungeon", "in": "path", "description": "Slug of the dungeon you want to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DungeonWrap" } } } } } } }, "/api/v1/route": { "get": { "tags": [ "Route" ], "summary": "Get a list of routes", "operationId": "getRoutes", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DungeonRouteSummaryEnvelope" } } } } } } }, "/api/v1/route/{route}": { "get": { "tags": [ "Route" ], "summary": "Get the details of a single route", "operationId": "getRoute", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DungeonRouteWrap" } } } } } } }, "/api/v1/route/{route}/thumbnail": { "post": { "tags": [ "Route" ], "summary": "Create a new thumbnail for a route you can view", "operationId": "createThumbnailsByRoute", "parameters": [ { "name": "route", "in": "path", "description": "Public key of the route you want to generate a thumbnail for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request object containing all parameters required to generate a thumbnail", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteThumbnailRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteThumbnailJobEnvelope" } } } } } } }, "/api/v1/route/thumbnailJob/{thumbnailJobId}": { "get": { "tags": [ "Route" ], "summary": "Return the status of a thumbnail job", "operationId": "getThumbnailJob", "parameters": [ { "name": "thumbnailJobId", "in": "path", "description": "The ID of the thumbnail job you want to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteThumbnailJobEnvelope" } } } } } } } }, "components": { "schemas": { "CombatLogRouteChallengeMode": { "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "success": { "type": "boolean", "nullable": true }, "durationMs": { "type": "integer" }, "parTimeMs": { "type": "integer" }, "timerFraction": { "type": "number", "format": "float" }, "challengeModeId": { "type": "integer" }, "level": { "type": "integer" }, "numDeaths": { "type": "integer" }, "affixes": { "type": "array", "items": { "type": "integer" } } }, "type": "object" }, "CombatLogRouteCoord": { "properties": { "x": { "type": "number", "format": "float" }, "y": { "type": "number", "format": "float" }, "uiMapId": { "type": "integer" } }, "type": "object" }, "CombatLogRouteCorrectionRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CombatLogRouteRequest" }, { "properties": { "metadata": { "$ref": "#/components/schemas/CombatLogRouteMetadata" }, "settings": { "$ref": "#/components/schemas/CombatLogRouteSettings" }, "challengeMode": { "$ref": "#/components/schemas/CombatLogRouteChallengeMode" }, "npcs": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteNpcCorrection" } }, "spells": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteSpellCorrection" }, "nullable": true }, "playerDeaths": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRoutePlayerDeathCorrection" }, "nullable": true } }, "type": "object" } ] }, "CombatLogRouteMetadata": { "properties": { "runId": { "type": "string" }, "keystoneRunId": { "type": "integer", "nullable": true }, "loggedRunId": { "type": "integer" }, "period": { "description": "The week of the season this run was recorded in, where 1 is the first week of the season", "type": "integer" }, "season": { "type": "string" }, "regionId": { "description": "The ID of the region that this run was recorded on", "type": "integer" }, "realmType": { "description": "The type of realm, such as 'live', 'beta' or 'ptr' etc.", "type": "string" }, "wowInstanceId": { "type": "integer", "nullable": true } }, "type": "object" }, "CombatLogRouteNpcCorrection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CombatLogRouteNpc" }, { "properties": { "npcId": { "description": "This class is used when Raider.io sends combat log info to our API, we then push it through ARC and this correction class\nis used to give info back about its original coordinate AND the corrected coordinate:\n\n{\n\"npcId\": 190342,\n\"spawnUid\": \"00023C8AAD\",\n\"engagedAt\": \"2023-07-22T19:04:45.134+00:00\",\n\"diedAt\": \"2023-07-22T19:05:08.545+00:00\",\n\"coord\": {\n\"x\": -184.38,\n\"y\": -17.76,\n\"uiMapId\": 2082\n},\n\"coordEnemy\": {\n\"x\": -187.4,\n\"y\": -27.2,\n\"uiMapId\": 2082\n}\n}", "type": "integer" }, "spawnUid": { "type": "string" }, "engagedAt": { "type": "string", "format": "date-time" }, "diedAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" }, "coordEnemy": { "$ref": "#/components/schemas/CombatLogRouteCoord" }, "gridCoord": { "$ref": "#/components/schemas/CombatLogRouteCoord" }, "gridCoordEnemy": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" } ] }, "CombatLogRouteNpc": { "properties": { "npcId": { "type": "integer" }, "spawnUid": { "type": "string" }, "engagedAt": { "type": "string", "format": "date-time" }, "diedAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" }, "CombatLogRoutePlayerDeathCorrection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CombatLogRoutePlayerDeath" }, { "properties": { "characterId": { "type": "integer" }, "classId": { "type": "integer" }, "specId": { "type": "integer" }, "itemLevel": { "type": "number", "format": "float" }, "diedAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" }, "gridCoord": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" } ] }, "CombatLogRoutePlayerDeath": { "properties": { "characterId": { "type": "integer" }, "classId": { "type": "integer" }, "specId": { "type": "integer" }, "itemLevel": { "type": "number", "format": "float" }, "diedAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" }, "CombatLogRouteRequest": { "properties": { "metadata": { "$ref": "#/components/schemas/CombatLogRouteMetadata" }, "settings": { "$ref": "#/components/schemas/CombatLogRouteSettings" }, "challengeMode": { "$ref": "#/components/schemas/CombatLogRouteChallengeMode" }, "npcs": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteNpc" } }, "spells": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteSpell" }, "nullable": true }, "playerDeaths": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRoutePlayerDeath" }, "nullable": true } }, "type": "object" }, "CombatLogRouteRoster": { "properties": { "numMembers": { "type": "integer" }, "averageItemLevel": { "type": "number", "format": "float" }, "characterIds": { "type": "array", "items": { "type": "integer" } }, "specIds": { "type": "array", "items": { "type": "integer" } }, "classIds": { "type": "array", "items": { "type": "integer" } } }, "type": "object" }, "CombatLogRouteSettings": { "properties": { "temporary": { "type": "boolean", "nullable": true }, "debugIcons": { "type": "boolean", "nullable": true }, "mappingVersion": { "type": "integer", "nullable": true } }, "type": "object" }, "CombatLogRouteSpellCorrection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CombatLogRouteSpell" }, { "properties": { "spellId": { "type": "integer" }, "playerUid": { "type": "string" }, "castAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" }, "gridCoord": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" } ] }, "CombatLogRouteSpell": { "properties": { "spellId": { "type": "integer" }, "playerUid": { "type": "string" }, "castAt": { "type": "string", "format": "date-time" }, "coord": { "$ref": "#/components/schemas/CombatLogRouteCoord" } }, "type": "object" }, "RouteThumbnailRequest": { "properties": { "viewportWidth": { "type": "integer", "maximum": "1620", "minimum": "768", "example": "900", "nullable": true }, "viewportHeight": { "type": "integer", "maximum": "1080", "minimum": "512", "example": "600", "nullable": true }, "imageWidth": { "type": "integer", "maximum": "1620", "minimum": "192", "example": "900", "nullable": true }, "imageHeight": { "type": "integer", "maximum": "1080", "minimum": "128", "example": "600", "nullable": true }, "zoomLevel": { "type": "number", "format": "float", "maximum": "5", "minimum": "1", "example": "2.2", "nullable": true }, "quality": { "type": "integer", "maximum": "100", "minimum": "0", "example": "90", "nullable": true } }, "type": "object" }, "Affix": { "properties": { "id": { "type": "integer", "example": "9" }, "name": { "description": "The name of the affix in English", "type": "string", "example": "Bolstering" } }, "type": "object" }, "AffixGroup": { "properties": { "affixes": { "type": "array", "items": { "$ref": "#/components/schemas/Affix" } } }, "type": "object" }, "CombatLogRouteRequestCorrection": { "properties": { "metadata": { "$ref": "#/components/schemas/CombatLogRouteMetadata" }, "settings": { "$ref": "#/components/schemas/CombatLogRouteSettings" }, "challengeMode": { "$ref": "#/components/schemas/CombatLogRouteChallengeMode" }, "npcs": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteNpcCorrection" } }, "spells": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRouteSpellCorrection" } }, "playerDeaths": { "type": "array", "items": { "$ref": "#/components/schemas/CombatLogRoutePlayerDeathCorrection" } } }, "type": "object" }, "DungeonEnvelope": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dungeon" } } }, "type": "object" }, "Dungeon": { "properties": { "id": { "type": "integer", "example": 69 }, "expansion": { "description": "The key of the expansion this dungeon belongs to", "type": "string", "example": "tww" }, "name": { "description": "The English dungeon name", "type": "string", "example": "The Stonevault" }, "slug": { "description": "The URL friendly slug of the dungeon's name", "type": "string", "example": "the-stonevault" }, "key": { "description": "The unique identifier for this dungeon", "type": "string", "example": "thestonevault" }, "zoneId": { "description": "The zone ID of the dungeon. Found on the Wowhead page of this dungeon", "type": "integer", "example": 14938 }, "mapId": { "description": "The map ID of the dungeon. Found on https://wago.tools/db2/Map", "type": "integer", "example": 2652 }, "instanceId": { "description": "The instance ID of the dungeon. Found on https://wago.tools/db2/JournalInstance", "type": "integer", "example": 1269 }, "challengeModeId": { "description": "The challenge mode ID of the dungeon. Found on https://wago.tools/db2/MapChallengeMode", "type": "integer", "example": 501 }, "raid": { "description": "True if this dungeon is a raid", "type": "boolean", "example": 0 }, "heatmapEnabled": { "description": "Whether a heatmap is available for this dungeon", "type": "boolean", "example": 0 }, "combinedViewEnabled": { "description": "Whether a combined view (MDT-style) is available for this dungeon", "type": "boolean", "example": 0 }, "speedrunEnabled": { "description": "Whether speedrun is enabled for this dungeon", "type": "boolean", "example": 0 }, "speedrunDifficulty10ManEnabled": { "description": "Whether 10-man difficulty is enabled for speedrunning", "type": "boolean", "example": 0 }, "speedrunDifficulty25ManEnabled": { "description": "Whether 25-man difficulty is enabled for speedrunning", "type": "boolean", "example": 0 }, "floors": { "type": "array", "items": { "$ref": "#/components/schemas/Floor" } } }, "type": "object" }, "DungeonWrap": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Dungeon" } }, "type": "object" }, "DungeonRouteLinks": { "properties": { "view": { "type": "string", "example": "https://keystone.guru/route/ara-kara-city-of-echoes/01ta7yg/ara-kara-city-of-echoes" }, "edit": { "type": "string", "example": "https://keystone.guru/route/ara-kara-city-of-echoes/01ta7yg/ara-kara-city-of-echoes/edit" }, "embed": { "type": "string", "example": "https://keystone.guru/route/ara-kara-city-of-echoes/01ta7yg/ara-kara-city-of-echoes/embed" }, "thumbnails": { "type": "array", "items": { "type": "string", "example": "https://uploads.keystone.guru/route_thumbnails/01ta7yg_1.jpg" } } }, "type": "object" }, "DungeonRoute": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DungeonRouteSummaryWrap" }, { "properties": { "dungeonId": { "type": "integer", "example": 1 }, "publicKey": { "type": "string", "example": "MS4cR1S" }, "title": { "type": "string", "example": "My dungeon route" }, "enemyForces": { "type": "integer", "example": 100 }, "enemyForcesRequired": { "type": "integer", "example": 100 }, "expiresAt": { "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00Z" }, "pulls": { "type": "array", "items": { "$ref": "#/components/schemas/Pull" } }, "author": { "$ref": "#/components/schemas/User" }, "affixGroups": { "type": "array", "items": { "$ref": "#/components/schemas/AffixGroup" } }, "links": { "$ref": "#/components/schemas/DungeonRouteLinks" } }, "type": "object" } ] }, "DungeonRouteWrap": { "required": [ "data" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/DungeonRouteSummaryWrap" }, { "properties": { "data": { "$ref": "#/components/schemas/DungeonRoute" } }, "type": "object" } ] }, "DungeonRouteSummaryEnvelope": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DungeonRouteSummary" } } }, "type": "object" }, "DungeonRouteSummary": { "properties": { "dungeonId": { "type": "integer", "example": 1 }, "publicKey": { "type": "string", "example": "MS4cR1S" }, "title": { "type": "string", "example": "My dungeon route" }, "enemyForces": { "type": "integer", "example": 100 }, "enemyForcesRequired": { "type": "integer", "example": 100 }, "expiresAt": { "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00Z" }, "pullCount": { "type": "integer", "example": 16 }, "author": { "$ref": "#/components/schemas/User" }, "affixGroups": { "type": "array", "items": { "$ref": "#/components/schemas/AffixGroup" } }, "links": { "$ref": "#/components/schemas/DungeonRouteLinks" } }, "type": "object" }, "DungeonRouteSummaryWrap": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DungeonRouteSummary" } }, "type": "object" }, "RouteThumbnailJobEnvelope": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RouteThumbnailJob" } } }, "type": "object" }, "RouteThumbnailJobLinks": { "properties": { "status": { "type": "string", "example": "https://keystone.guru/api/v1/thumbnailJob/1" }, "result": { "type": "string", "example": "https://uploads.keystone.guru/thumbnails_custom/MS4cR1S/1.jpg" } }, "type": "object" }, "RouteThumbnailJob": { "properties": { "id": { "type": "integer", "example": "69" }, "publicKey": { "type": "string", "example": "MS4cR1S" }, "floorIndex": { "description": "If the dungeon supports combined floors, the highest floor_index represents the floor with all combined floors.", "type": "integer", "example": "1" }, "status": { "type": "integer", "enum": [ "queued", "completed", "expired", "error" ] }, "viewportWidth": { "type": "integer", "example": "900" }, "viewportHeight": { "type": "integer", "example": "600" }, "imageWidth": { "type": "integer", "example": "900" }, "imageHeight": { "type": "integer", "example": "600" }, "zoomLevel": { "type": "number", "format": "float", "example": "2.2" }, "quality": { "type": "integer", "example": "90" }, "queueSize": { "type": "integer", "example": "493" }, "estimatedCompletion": { "type": "string", "example": "2024-01-25T20:22:14.000000Z" }, "expiresAt": { "type": "string", "example": "2025-01-25T20:22:14.000000Z" }, "links": { "$ref": "#/components/schemas/RouteThumbnailJobLinks" } }, "type": "object" }, "Floor": { "properties": { "id": { "type": "integer", "example": "69" }, "uiMapId": { "type": "integer", "example": "259" }, "name": { "description": "The English name of the floor", "type": "string", "example": "The Stonevault" }, "default": { "description": "True if this is the floor any route for the dungeon opens up to", "type": "boolean", "example": "true" }, "ingameMinX": { "description": "In-game coordinates of the minimum X value of the floor", "type": "number", "format": "float", "example": "437.19" }, "ingameMinY": { "description": "In-game coordinates of the minimum Y value of the floor", "type": "number", "format": "float", "example": "-397.08" }, "ingameMaxX": { "description": "In-game coordinates of the maximum X value of the floor", "type": "number", "format": "float", "example": "-503.44" }, "ingameMaxY": { "description": "In-game coordinates of the maximum Y value of the floor", "type": "number", "format": "float", "example": "230" } }, "type": "object" }, "PullEnemy": { "properties": { "npcId": { "type": "integer", "example": "222923" }, "mdtIndex": { "type": "integer", "example": "5" }, "enemyForces": { "type": "integer", "example": "4" } }, "type": "object" }, "Pull": { "properties": { "description": { "type": "string", "example": "Pull description, if any", "nullable": true }, "spells": { "type": "array", "items": { "type": "integer", "example": "403631" } }, "enemies": { "type": "array", "items": { "$ref": "#/components/schemas/PullEnemy" } } }, "type": "object" }, "PaginationLinks": { "properties": { "first": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon?page=1" }, "last": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon?page=3" }, "prev": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon?page=1", "nullable": true }, "next": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon?page=2", "nullable": true } }, "type": "object" }, "PaginationMetaLinks": { "properties": { "url": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon?page=1", "nullable": true }, "label": { "type": "string", "example": "Next »" }, "active": { "type": "boolean" } }, "type": "object" }, "PaginationMeta": { "properties": { "current_page": { "type": "integer", "example": "1" }, "from": { "type": "integer", "example": "1" }, "last_page": { "type": "integer", "example": "5" }, "path": { "type": "string", "example": "https://keystone.guru/api/v1/dungeon" }, "per_page": { "type": "integer", "example": "50" }, "to": { "type": "integer", "example": "50" }, "total": { "type": "integer", "example": "121" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/PaginationMetaLinks" } } }, "type": "object" }, "UserLinks": { "properties": { "view": { "type": "string", "example": "https://keystone.guru/profile/1" }, "avatar": { "type": "string", "example": "https://keystone.guru/storage/uploads/myavatar.jpg" } }, "type": "object" }, "User": { "properties": { "publicKey": { "type": "string", "example": "MS4cR1S" }, "name": { "type": "string", "example": "John Doe" }, "links": { "$ref": "#/components/schemas/UserLinks" }, "avatar": { "type": "string", "example": "https://uploads.keystone.guru/uploads/5kf5hGB0jalkkxewRio6XEQP0KIaS9XJDFropTn7.png" } }, "type": "object" } } }, "tags": [ { "name": "Dungeon", "description": "Dungeon" }, { "name": "Route", "description": "Route" } ] }