openapi: 3.0.0 info: version: 2.0.0 title: TWHelp API description: REST API to interact with [TWHelp](https://tribalwarshelp.com). contact: name: Dawid Wysokiński url: https://dwysokinski.me email: contact@dwysokinski.me license: name: MIT tags: - name: versions - name: servers - name: tribes servers: - url: "{scheme}://{hostname}/api" variables: scheme: default: http enum: - http - https hostname: default: localhost:9234 paths: /v2/versions: get: operationId: listVersions tags: - versions description: List versions parameters: - $ref: "#/components/parameters/CursorQueryParam" - $ref: "#/components/parameters/LimitQueryParam" responses: 200: $ref: "#/components/responses/ListVersionsResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}: get: operationId: getVersion tags: - versions description: Get a version parameters: - $ref: "#/components/parameters/VersionCodePathParam" responses: 200: $ref: "#/components/responses/GetVersionResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers: get: operationId: listServers tags: - versions - servers description: List servers parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/CursorQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/ServerOpenQueryParam" responses: 200: $ref: "#/components/responses/ListServersResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}: get: operationId: getServer tags: - versions - servers description: Get a server parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" responses: 200: $ref: "#/components/responses/GetServerResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}/config: get: operationId: getServerConfig tags: - versions - servers description: Get server config parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" responses: 200: $ref: "#/components/responses/GetServerConfigResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}/building-info: get: operationId: getBuildingInfo tags: - versions - servers description: Get building info parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" responses: 200: $ref: "#/components/responses/GetBuildingInfoResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}/unit-info: get: operationId: getUnitInfo tags: - versions - servers description: Get unit info parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" responses: 200: $ref: "#/components/responses/GetUnitInfoResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}/tribes: get: operationId: listTribes tags: - versions - servers - tribes description: List tribes parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" - $ref: "#/components/parameters/CursorQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/TribeDeletedQueryParam" - $ref: "#/components/parameters/TribeSortQueryParam" - $ref: "#/components/parameters/TribeTagQueryParam" responses: 200: $ref: "#/components/responses/ListTribesResponse" default: $ref: "#/components/responses/ErrorResponse" /v2/versions/{versionCode}/servers/{serverKey}/tribes/{tribeId}: get: operationId: getTribe tags: - versions - servers - tribes description: Get a tribe parameters: - $ref: "#/components/parameters/VersionCodePathParam" - $ref: "#/components/parameters/ServerKeyPathParam" - $ref: "#/components/parameters/TribeIdPathParam" responses: 200: $ref: "#/components/responses/GetTribeResponse" default: $ref: "#/components/responses/ErrorResponse" components: schemas: Error: type: object required: - code - message additionalProperties: false properties: code: type: string example: length-out-of-range message: type: string path: type: array description: References field where an error occurred. items: type: string x-go-type-skip-optional-pointer: true params: type: object description: Additional data related to the error. Can be used for i18n. additionalProperties: true x-go-type-skip-optional-pointer: true Version: type: object required: - code - host - name - timezone properties: code: type: string example: pl host: type: string format: hostname example: www.tribalwars.net name: type: string example: Poland timezone: type: string example: Europe/Warsaw Server: type: object required: - key - open - url - numPlayers - numTribes - numVillages - numBarbarianVillages - numBonusVillages - numPlayerVillages - createdAt properties: key: type: string example: pl151 open: type: boolean url: type: string format: uri example: https://pl151.plemiona.pl numPlayers: type: integer playerDataSyncedAt: type: string format: date-time numTribes: type: integer tribeDataSyncedAt: type: string format: date-time numVillages: type: integer numBarbarianVillages: type: integer numBonusVillages: type: integer numPlayerVillages: type: integer villageDataSyncedAt: type: string format: date-time ennoblementDataSyncedAt: type: string format: date-time createdAt: type: string format: date-time ServerConfig: type: object required: - ally - build - buildings - commands - coord - game - misc - moral - newbie - night - sitter - sleep - snob - speed - unitSpeed - win properties: ally: $ref: "#/components/schemas/ServerConfigAlly" build: $ref: "#/components/schemas/ServerConfigBuild" buildings: $ref: "#/components/schemas/ServerConfigBuildings" commands: $ref: "#/components/schemas/ServerConfigCommands" coord: $ref: "#/components/schemas/ServerConfigCoord" game: $ref: "#/components/schemas/ServerConfigGame" misc: $ref: "#/components/schemas/ServerConfigMisc" moral: type: integer newbie: $ref: "#/components/schemas/ServerConfigNewbie" night: $ref: "#/components/schemas/ServerConfigNight" sitter: $ref: "#/components/schemas/ServerConfigSitter" sleep: $ref: "#/components/schemas/ServerConfigSleep" snob: $ref: "#/components/schemas/ServerConfigSnob" speed: type: number format: double unitSpeed: type: number format: double win: $ref: "#/components/schemas/ServerConfigWin" ServerConfigAlly: type: object required: - allytimeSupport - fixedAllies - levels - limit - noHarm - noJoin - noLeave - noOtherSupport - noOtherSupportType - pointsMemberCount - warsAutoacceptDays - warsMemberRequirement - warsPointsRequirement - xpRequirements properties: allytimeSupport: type: integer fixedAllies: type: integer levels: type: integer limit: type: integer noHarm: type: integer noJoin: type: integer noLeave: type: integer noOtherSupport: type: integer noOtherSupportType: type: integer pointsMemberCount: type: integer warsAutoacceptDays: type: integer warsMemberRequirement: type: integer warsPointsRequirement: type: integer xpRequirements: type: string ServerConfigBuild: type: object required: - destroy properties: destroy: type: integer ServerConfigBuildings: type: object required: - customBarracks - customChurch - customFarm - customGarage - customHide - customIron - customMain - customMarket - customPlace - customSmith - customSnob - customStable - customStatue - customStone - customStorage - customWall - customWatchtower - customWood properties: customBarracks: type: integer customChurch: type: integer customFarm: type: integer customGarage: type: integer customHide: type: integer customIron: type: integer customMain: type: integer customMarket: type: integer customPlace: type: integer customSmith: type: integer customSnob: type: integer customStable: type: integer customStatue: type: integer customStone: type: integer customStorage: type: integer customWall: type: integer customWatchtower: type: integer customWood: type: integer ServerConfigCommands: type: object required: - commandCancelTime - millisArrival properties: commandCancelTime: type: integer millisArrival: type: integer ServerConfigCoord: type: object required: - bonusNew - bonusVillages - emptyVillages - func - inner - mapSize - nobleRestart - selectStart - startVillages - villageMoveWait properties: bonusNew: type: integer bonusVillages: type: integer emptyVillages: type: integer func: type: integer inner: type: integer mapSize: type: integer nobleRestart: type: integer selectStart: type: integer startVillages: type: integer villageMoveWait: type: integer ServerConfigGame: type: object required: - archer - barbarianMaxPoints - barbarianRise - barbarianShrink - baseProduction - buildtimeFormula - church - event - fakeLimit - farmLimit - hauls - haulsBase - haulsMax - knight - knightNewItems - scavenging - stronghold - suppressEvents - tech - watchtower properties: archer: type: integer barbarianMaxPoints: type: integer barbarianRise: type: number format: double barbarianShrink: type: integer baseProduction: type: integer buildtimeFormula: type: integer church: type: integer event: type: integer fakeLimit: type: number format: double farmLimit: type: integer hauls: type: integer haulsBase: type: integer haulsMax: type: integer knight: type: integer knightNewItems: type: integer scavenging: type: integer stronghold: type: integer suppressEvents: type: integer tech: type: integer watchtower: type: integer ServerConfigMisc: type: object required: - killRanking - tradeCancelTime - tutorial properties: killRanking: type: integer tradeCancelTime: type: integer tutorial: type: integer ServerConfigNewbie: type: object required: - days - ratio - ratioDays - removeNewbieVillages properties: days: type: integer ratio: type: integer ratioDays: type: integer removeNewbieVillages: type: integer ServerConfigNight: type: object required: - active - defFactor - duration - endHour - startHour properties: active: type: integer defFactor: type: number format: double duration: type: integer endHour: type: integer startHour: type: integer ServerConfigSitter: type: object required: - allow properties: allow: type: integer ServerConfigSleep: type: object required: - active - delay - max - maxAwake - min - minAwake - warnTime properties: active: type: integer delay: type: integer max: type: integer maxAwake: type: integer min: type: integer minAwake: type: integer warnTime: type: integer ServerConfigSnob: type: object required: - cheapRebuild - coinIron - coinStone - coinWood - factor - gold - maxDist - noBarbConquer - rise properties: cheapRebuild: type: integer coinIron: type: integer coinStone: type: integer coinWood: type: integer factor: type: number format: double gold: type: integer maxDist: type: integer noBarbConquer: type: integer rise: type: integer ServerConfigWin: type: object required: - check properties: check: type: integer Unit: type: object required: - attack - buildTime - carry - defense - defenseArcher - defenseCavalry - pop - speed properties: attack: type: integer buildTime: type: number format: double carry: type: integer defense: type: integer defenseArcher: type: integer defenseCavalry: type: integer pop: type: integer speed: type: number format: double UnitInfo: type: object required: - archer - axe - catapult - heavy - knight - light - marcher - militia - ram - snob - spear - spy - sword properties: archer: $ref: "#/components/schemas/Unit" axe: $ref: "#/components/schemas/Unit" catapult: $ref: "#/components/schemas/Unit" heavy: $ref: "#/components/schemas/Unit" knight: $ref: "#/components/schemas/Unit" light: $ref: "#/components/schemas/Unit" marcher: $ref: "#/components/schemas/Unit" militia: $ref: "#/components/schemas/Unit" ram: $ref: "#/components/schemas/Unit" snob: $ref: "#/components/schemas/Unit" spear: $ref: "#/components/schemas/Unit" spy: $ref: "#/components/schemas/Unit" sword: $ref: "#/components/schemas/Unit" Building: type: object required: - buildTime - buildTimeFactor - iron - ironFactor - maxLevel - minLevel - pop - popFactor - stone - stoneFactor - wood - woodFactor properties: buildTime: type: number format: double buildTimeFactor: type: number format: double iron: type: integer ironFactor: type: number format: double maxLevel: type: integer minLevel: type: integer pop: type: integer popFactor: type: number format: double stone: type: integer stoneFactor: type: number format: double wood: type: integer woodFactor: type: number format: double BuildingInfo: type: object required: - barracks - farm - garage - hide - iron - main - market - place - smith - snob - stable - statue - stone - storage - wall - watchtower - wood properties: barracks: $ref: "#/components/schemas/Building" farm: $ref: "#/components/schemas/Building" garage: $ref: "#/components/schemas/Building" hide: $ref: "#/components/schemas/Building" iron: $ref: "#/components/schemas/Building" main: $ref: "#/components/schemas/Building" market: $ref: "#/components/schemas/Building" place: $ref: "#/components/schemas/Building" smith: $ref: "#/components/schemas/Building" snob: $ref: "#/components/schemas/Building" stable: $ref: "#/components/schemas/Building" statue: $ref: "#/components/schemas/Building" stone: $ref: "#/components/schemas/Building" storage: $ref: "#/components/schemas/Building" wall: $ref: "#/components/schemas/Building" watchtower: $ref: "#/components/schemas/Building" wood: $ref: "#/components/schemas/Building" TribeOpponentsDefeated: type: object required: - rankAtt - scoreAtt - rankDef - scoreDef - rankTotal - scoreTotal properties: rankAtt: type: integer scoreAtt: type: integer rankDef: type: integer scoreDef: type: integer rankTotal: type: integer scoreTotal: type: integer Tribe: type: object required: - id - name - tag - profileUrl - points - allPoints - numMembers - numVillages - rank - dominance - opponentsDefeated - bestRank - bestRankAt - mostVillages - mostVillagesAt - mostPoints - mostPointsAt - createdAt properties: id: type: integer name: type: string tag: type: string profileUrl: type: string format: uri points: type: integer allPoints: type: integer numMembers: type: integer numVillages: type: integer rank: type: integer dominance: type: number format: double opponentsDefeated: $ref: "#/components/schemas/TribeOpponentsDefeated" bestRank: type: integer bestRankAt: type: string format: date-time mostVillages: type: integer mostVillagesAt: type: string format: date-time mostPoints: type: integer mostPointsAt: type: string format: date-time createdAt: type: string format: date-time deletedAt: type: string format: date-time Cursor: type: object x-go-type-skip-optional-pointer: true properties: self: description: Cursor pointing to the current page. type: string minLength: 1 maxLength: 1000 x-go-type-skip-optional-pointer: true next: description: Cursor pointing to the next page. type: string minLength: 1 maxLength: 1000 x-go-type-skip-optional-pointer: true PaginationResponse: type: object properties: cursor: $ref: "#/components/schemas/Cursor" parameters: CursorQueryParam: in: query name: cursor schema: type: string minLength: 1 maxLength: 1000 required: false LimitQueryParam: in: query name: limit schema: type: integer minimum: 1 required: false ServerOpenQueryParam: name: open in: query description: true=only open servers, false=only closed servers, by default both open and closed servers are returned schema: type: boolean required: false TribeDeletedQueryParam: name: deleted in: query description: true=only deleted tribes, false=only existing tribes, by default both existing and deleted tribes are returned schema: type: boolean required: false TribeSortQueryParam: name: sort in: query description: Order matters! schema: type: array items: type: string enum: - odScoreAtt:ASC - odScoreAtt:DESC - odScoreDef:ASC - odScoreDef:DESC - odScoreTotal:ASC - odScoreTotal:DESC - points:ASC - points:DESC - dominance:ASC - dominance:DESC - deletedAt:ASC - deletedAt:DESC maxItems: 2 TribeTagQueryParam: name: tag in: query schema: type: array items: type: string maxItems: 100 VersionCodePathParam: in: path name: versionCode required: true schema: type: string ServerKeyPathParam: in: path name: serverKey required: true schema: type: string TribeIdPathParam: in: path name: tribeId required: true schema: type: integer minimum: 0 responses: ListVersionsResponse: description: "" content: application/json: schema: allOf: - $ref: "#/components/schemas/PaginationResponse" - type: object required: - data properties: data: type: array items: $ref: "#/components/schemas/Version" GetVersionResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/Version" ListServersResponse: description: "" content: application/json: schema: allOf: - $ref: "#/components/schemas/PaginationResponse" - type: object required: - data properties: data: type: array items: $ref: "#/components/schemas/Server" GetServerResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/Server" GetServerConfigResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/ServerConfig" GetUnitInfoResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/UnitInfo" GetBuildingInfoResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/BuildingInfo" ListTribesResponse: description: "" content: application/json: schema: allOf: - $ref: "#/components/schemas/PaginationResponse" - type: object required: - data properties: data: type: array items: $ref: "#/components/schemas/Tribe" GetTribeResponse: description: "" content: application/json: schema: type: object required: - data properties: data: $ref: "#/components/schemas/Tribe" ErrorResponse: description: Default error response. content: application/json: schema: type: object required: - errors additionalProperties: false properties: errors: type: array items: $ref: "#/components/schemas/Error"