{"openapi":"3.1.0","info":{"title":"boilmaster","version":"1-9c95715"},"paths":{"/asset":{"get":{"tags":["assets"],"summary":"read an asset","description":"Read an asset from the game at the specified path, converting it into a usable format. If no valid conversion between the game file type and specified format exists, an error will be returned.","parameters":[{"in":"query","name":"version","description":"Game version to utilise for this query.","schema":{"description":"Game version to utilise for this query.","type":["string","null"]},"style":"form"},{"in":"query","name":"path","description":"Game path of the asset to retrieve.","required":true,"schema":{"description":"Game path of the asset to retrieve.","examples":["ui/icon/051000/051474_hr1.tex"],"type":"string"},"style":"form"},{"in":"query","name":"format","description":"Format that the asset should be converted into.","required":true,"schema":{"description":"Format that the asset should be converted into.","examples":["png"],"$ref":"#/components/schemas/SchemaFormat"},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"byte stream","content":{"image/jpeg":{},"image/png":{},"image/webp":{}}},"304":{"description":"not modified"}}}},"/asset/map/{territory}/{index}":{"get":{"tags":["assets"],"summary":"compose a map","description":"Retrieve the specified map, composing it from split source files if necessary.","parameters":[{"in":"path","name":"territory","description":"Territory of the map to be retrieved. This typically takes the form of 4 characters, [letter][number][letter][number]. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","required":true,"schema":{"description":"Territory of the map to be retrieved. This typically takes the form of 4 characters, [letter][number][letter][number]. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","examples":["s1d1"],"type":"string"},"style":"simple"},{"in":"path","name":"index","description":"Index of the map within the territory. This invariably takes the form of a two-digit zero-padded number. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","required":true,"schema":{"description":"Index of the map within the territory. This invariably takes the form of a two-digit zero-padded number. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","examples":["00"],"type":"string"},"style":"simple"},{"in":"query","name":"version","description":"Game version to utilise for this query.","schema":{"description":"Game version to utilise for this query.","type":["string","null"]},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"byte stream","content":{"image/jpeg":{}}},"304":{"description":"not modified"}}}},"/search":{"get":{"tags":["search"],"summary":"execute a search query","description":"Fetch information about rows and their related data that match the provided search query.","parameters":[{"in":"query","name":"version","description":"Game version to utilise for this query.","schema":{"description":"Game version to utilise for this query.","type":["string","null"]},"style":"form"},{"in":"query","name":"query","description":"Search query to execute in this request. Must be specified if not querying a cursor. URL special characters, such as `+`, must be escaped to prevent mis-parses of the query.","schema":{"description":"Search query to execute in this request. Must be specified if not querying a cursor. URL special characters, such as `+`, must be escaped to prevent mis-parses of the query.","anyOf":[{"$ref":"#/components/schemas/QueryString"},{"type":"null"}]},"style":"form"},{"in":"query","name":"sheets","description":"List of excel sheets that the query should be run against. At least one must be specified if not querying a cursor.","schema":{"description":"List of excel sheets that the query should be run against. At least one must be specified if not querying a cursor.","type":["string","null"]},"style":"form"},{"in":"query","name":"cursor","description":"Continuation token to retrieve further results from a prior search request. If specified, takes priority over `query`.","schema":{"description":"Continuation token to retrieve further results from a prior search request. If specified, takes priority over `query`.","type":["string","null"],"format":"uuid"},"style":"form"},{"in":"query","name":"limit","description":"Maximum number of rows to return. To paginate, provide the cursor token provided in `next` to the `cursor` parameter.","schema":{"description":"Maximum number of rows to return. To paginate, provide the cursor token provided in `next` to the `cursor` parameter.","type":["integer","null"],"format":"uint","minimum":0.0},"style":"form"},{"in":"query","name":"language","description":"Language to use for data with no language otherwise specified in the fields filter.","schema":{"description":"Language to use for data with no language otherwise specified in the fields filter.","anyOf":[{"$ref":"#/components/schemas/SchemaLanguage"},{"type":"null"}]},"style":"form"},{"in":"query","name":"schema","description":"Schema that row data should be read with.","schema":{"description":"Schema that row data should be read with.","anyOf":[{"$ref":"#/components/schemas/SchemaSpecifier"},{"type":"null"}]},"style":"form"},{"in":"query","name":"fields","description":"Data fields to read for selected rows.","schema":{"description":"Data fields to read for selected rows.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"},{"in":"query","name":"transient","description":"Data fields to read for selected rows' transient row, if any is present.","schema":{"description":"Data fields to read for selected rows' transient row, if any is present.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"next":"bbe61a5e-7d22-41ec-9f5a-711c967c5624","results":[{"fields":{"FieldName":14},"row_id":1,"score":1.4129999876022339,"sheet":"SheetName"}],"schema":"source@version","version":"f815390159effefd"}}}}}}},"/sheet":{"get":{"tags":["sheets"],"summary":"list sheets","description":"List known excel sheets that can be read by the API.","parameters":[{"in":"query","name":"version","description":"Game version to utilise for this query.","schema":{"description":"Game version to utilise for this query.","type":["string","null"]},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse"},"example":{"sheets":[{"name":"Action"},{"name":"Item"},{"name":"Status"}]}}}}}}},"/sheet/{sheet}":{"get":{"tags":["sheets"],"summary":"list rows in a sheet","description":"Read information about one or more rows and their related data.","parameters":[{"in":"path","name":"sheet","description":"Name of the sheet to read.","required":true,"schema":{"description":"Name of the sheet to read.","type":"string"},"style":"simple"},{"in":"query","name":"rows","description":"Rows to fetch from the sheet, as a comma-separated list. Behavior is undefined if both `rows` and `after` are provided.","schema":{"description":"Rows to fetch from the sheet, as a comma-separated list. Behavior is undefined if both `rows` and `after` are provided.","type":"string","pattern":"^\\d+(:\\d+)?(,\\d+(:\\d+)?)*$"},"style":"form"},{"in":"query","name":"limit","description":"Maximum number of rows to return. To paginate, provide the last returned row to the next request's `after` parameter.","schema":{"description":"Maximum number of rows to return. To paginate, provide the last returned row to the next request's `after` parameter.","type":["integer","null"],"format":"uint","minimum":0.0},"style":"form"},{"in":"query","name":"after","description":"Fetch rows after the specified row. Behavior is undefined if both `rows` and `after` are provided.","schema":{"description":"Fetch rows after the specified row. Behavior is undefined if both `rows` and `after` are provided.","anyOf":[{"$ref":"#/components/schemas/RowSpecifier"},{"type":"null"}]},"style":"form"},{"in":"query","name":"language","description":"Language to use for data with no language otherwise specified in the fields filter.","schema":{"description":"Language to use for data with no language otherwise specified in the fields filter.","anyOf":[{"$ref":"#/components/schemas/SchemaLanguage"},{"type":"null"}]},"style":"form"},{"in":"query","name":"schema","description":"Schema that row data should be read with.","schema":{"description":"Schema that row data should be read with.","anyOf":[{"$ref":"#/components/schemas/SchemaSpecifier"},{"type":"null"}]},"style":"form"},{"in":"query","name":"fields","description":"Data fields to read for selected rows.","schema":{"description":"Data fields to read for selected rows.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"},{"in":"query","name":"transient","description":"Data fields to read for selected rows' transient row, if any is present.","schema":{"description":"Data fields to read for selected rows' transient row, if any is present.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SheetResponse"},"example":{"rows":[{"fields":{"FieldName":14},"row_id":1},{"fields":{"FieldName":14},"row_id":2}],"schema":"source@version","version":"f815390159effefd"}}}}}}},"/sheet/{sheet}/{row}":{"get":{"tags":["sheets"],"summary":"read a sheet row","description":"Read detailed, filterable information from a single sheet row and its related data.","parameters":[{"in":"path","name":"sheet","description":"Name of the sheet to read.","required":true,"schema":{"description":"Name of the sheet to read.","type":"string"},"style":"simple"},{"in":"path","name":"row","description":"Row to read.","required":true,"schema":{"description":"Row to read.","$ref":"#/components/schemas/RowSpecifier"},"style":"simple"},{"in":"query","name":"language","description":"Language to use for data with no language otherwise specified in the fields filter.","schema":{"description":"Language to use for data with no language otherwise specified in the fields filter.","anyOf":[{"$ref":"#/components/schemas/SchemaLanguage"},{"type":"null"}]},"style":"form"},{"in":"query","name":"schema","description":"Schema that row data should be read with.","schema":{"description":"Schema that row data should be read with.","anyOf":[{"$ref":"#/components/schemas/SchemaSpecifier"},{"type":"null"}]},"style":"form"},{"in":"query","name":"fields","description":"Data fields to read for selected rows.","schema":{"description":"Data fields to read for selected rows.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"},{"in":"query","name":"transient","description":"Data fields to read for selected rows' transient row, if any is present.","schema":{"description":"Data fields to read for selected rows' transient row, if any is present.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"style":"form"}],"responses":{"default":{"description":"failed operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"invalid request: example error response"}}}},"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowResponse"},"example":{"fields":{"FieldName":14},"row_id":1,"schema":"source@version","version":"f815390159effefd"}}}}}}},"/version":{"get":{"tags":["versions"],"summary":"list versions","description":"List versions understood by the API.","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionsResponse"},"example":{"versions":[{"key":"f815390159effefd","names":["7.0"]},{"key":"2139246928a48a9a","names":["7.01","latest"]}]}}}}}}}},"components":{"schemas":{"VersionQueryParams":{"title":"VersionQuery","description":"Query parameters accepted by endpoints that interact with versioned game data.","type":"object","properties":{"version":{"description":"Game version to utilise for this query.","type":["string","null"]}}},"AssetQuery":{"description":"Query parameters accepted by the asset endpoint.","type":"object","required":["format","path"],"properties":{"path":{"description":"Game path of the asset to retrieve.","examples":["ui/icon/051000/051474_hr1.tex"],"type":"string"},"format":{"description":"Format that the asset should be converted into.","examples":["png"],"$ref":"#/components/schemas/SchemaFormat"}}},"SchemaFormat":{"type":"string","enum":["jpg","png","webp"]},"ErrorResponse":{"description":"General purpose error response structure.","type":"object","required":["code","message"],"properties":{"code":{"description":"HTTP status code of the error. Will match the server response code.","$ref":"#/components/schemas/StatusCode"},"message":{"description":"Description of what went wrong.","type":"string"}}},"StatusCode":{"type":"integer","format":"uint16","minimum":0.0},"MapPath":{"description":"Path segments expected by the asset map endpoint.","type":"object","required":["index","territory"],"properties":{"territory":{"description":"Territory of the map to be retrieved. This typically takes the form of 4 characters, [letter][number][letter][number]. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","examples":["s1d1"],"type":"string"},"index":{"description":"Index of the map within the territory. This invariably takes the form of a two-digit zero-padded number. See `Map`'s `Id` field for examples of possible combinations of `territory` and `index`.","examples":["00"],"type":"string"}}},"SearchQuery":{"description":"Query paramters accepted by the search endpoint.","type":"object","properties":{"query":{"description":"Search query to execute in this request. Must be specified if not querying a cursor. URL special characters, such as `+`, must be escaped to prevent mis-parses of the query.","anyOf":[{"$ref":"#/components/schemas/QueryString"},{"type":"null"}]},"sheets":{"description":"List of excel sheets that the query should be run against. At least one must be specified if not querying a cursor.","type":["string","null"]},"cursor":{"description":"Continuation token to retrieve further results from a prior search request. If specified, takes priority over `query`.","type":["string","null"],"format":"uuid"},"limit":{"description":"Maximum number of rows to return. To paginate, provide the cursor token provided in `next` to the `cursor` parameter.","type":["integer","null"],"format":"uint","minimum":0.0}}},"QueryString":{"description":"A query string for searching excel data.\n\nQueries are formed of clauses, which take the basic form of `[specifier][operation][value]`, i.e. `Name=\"Example\"`. Multiple clauses may be specified by seperating them with whitespace, i.e. `Foo=1 Bar=2`.\n\nLike field filters, clause specifiers may use dot notation to specify fields inside structs and relations (i.e. `Foo.Bar=1)`, as well as language tags to target fields in particular languages (i.e. `Foo@ja=1`).\n\nArrays must be selected explicitly (i.e. `Foo[]=1`), resulting in a match for any value within the array. An index can be used to reduce the search space (i.e. `Foo[1]=1`).\n\nBy default, results will match at least one clause, with higher relevance scores for those that match more. To modify this behavior, clauses can decorated. `+clause` specifies that the clause _must_ be matched for any result returned, and `-clause` specifies that it _must not_ be matched.\n\nTo represent more involved boolean matching, clauses may be grouped with parentheses. `+(a b) +c` will require that either clauses a _or_ b must match, in addition to c matching.\n\nSupported operations:\n\n- partial string match: `key~\"value\"`\n\n- exact equality: `key=value`\n\n- numeric comparison: `key>=value`, `key>value`, `key<=value`, `key<value`\n\nSupported value types:\n\n- string: `\"example\"`\n\n- number: `1`, `-1`, `1.0`\n\n- boolean: `true`, `false`","type":"string"},"RowReaderQuery":{"description":"Query parameters accepted by endpoints that retrieve excel row data.","type":"object","properties":{"language":{"description":"Language to use for data with no language otherwise specified in the fields filter.","anyOf":[{"$ref":"#/components/schemas/SchemaLanguage"},{"type":"null"}]},"schema":{"description":"Schema that row data should be read with.","anyOf":[{"$ref":"#/components/schemas/SchemaSpecifier"},{"type":"null"}]},"fields":{"description":"Data fields to read for selected rows.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]},"transient":{"description":"Data fields to read for selected rows' transient row, if any is present.","anyOf":[{"$ref":"#/components/schemas/FilterString"},{"type":"null"}]}}},"SchemaLanguage":{"description":"Known languages supported by the game data format. **NOTE:** Not all languages that are supported by the format are valid for all editions of the game. For example, the global game client acknowledges the existence of `chs` and `kr`, however does not provide any data for them.","type":"string","enum":["none","ja","en","de","fr","chs","cht","kr"]},"SchemaSpecifier":{"type":"string","pattern":"^.+(@.+)?$"},"FilterString":{"description":"A filter string for selecting fields within a row.\n\nFilters are comprised of a comma-seperated list of field paths, i.e. `a,b` will select the fields `a` and `b`.\n\nDecorators may be used to modify the way a field is read. They take the form of `@decorator(arguments)`, i.e. `field@lang(en)`. Currently accepted decorators:\n\n- `@lang(<language>)`: Overrides the query's language for the decorated field. Allows one query to access data for multiple languages. `language` accepts any valid `LanguageString`.\n\n- `@as(<format>)`: Overrides the default output format for the decorated field.\n\nCurrently accepted `format`s for `@as`:\n\n- `raw`: Prevents further processing, such as sheet relations, being performed on the decorated field. Has no effect on regular scalar fields.\n\n- `html`: Formats a string field as rich HTML. Invalid on non-string fields. Output will be a valid HTML fragment, however no stability guarantees are made over the precise markup used.\n\nNested fields may be selected using dot notation, i.e. `a.b` will select the field `b` contained in the struct `a`.\n\nArrays must be targeted if selecting fields within them, i.e. `a[].b` will select _all_ `b` fields of structs within the array `a`, however `a.b` will select nothing.","type":"string"},"SearchResponse":{"description":"Response structure for the search endpoint.","type":"object","required":["results","schema","version"],"properties":{"next":{"description":"A cursor that can be used to retrieve further results if available.","type":["string","null"],"format":"uuid"},"results":{"description":"Array of results found by the query, sorted by their relevance.","type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"schema":{"description":"The canonical specifier for the schema used in this response.","type":"string"},"version":{"description":"The canonical specifier for the version used in this response.","type":"string"}}},"SearchResult":{"description":"Result found by a search query, hydrated with data from the underlying excel row the result represents.","type":"object","required":["fields","row_id","score","sheet"],"properties":{"score":{"description":"Relevance score for this entry.\n\nThese values only loosely represent the relevance of an entry to the search query. No guarantee is given that the discrete values, nor resulting sort order, will remain stable.","type":"number","format":"float"},"sheet":{"description":"Excel sheet this result was found in.","type":"string"},"row_id":{"description":"ID of this row.","type":"integer","format":"uint32","minimum":0.0},"subrow_id":{"description":"Subrow ID of this row, when relevant.","type":["integer","null"],"format":"uint16","minimum":0.0},"fields":{"description":"Field values for this row, according to the current schema and field filter.","$ref":"#/components/schemas/ValueString"},"transient":{"description":"Field values for this row's transient row, if any is present, according to the current schema and transient filter.","anyOf":[{"$ref":"#/components/schemas/ValueString"},{"type":"null"}]}}},"ValueString":{"type":"object"},"ListResponse":{"description":"Response structure for the list endpoint.","type":"object","required":["sheets"],"properties":{"sheets":{"description":"Array of sheets known to the API.","type":"array","items":{"$ref":"#/components/schemas/SheetMetadata"}}}},"SheetMetadata":{"description":"Metadata about a single sheet.","type":"object","required":["name"],"properties":{"name":{"description":"The name of the sheet.","type":"string"}}},"SheetPath":{"description":"Path variables accepted by the sheet endpoint.","type":"object","required":["sheet"],"properties":{"sheet":{"description":"Name of the sheet to read.","type":"string"}}},"SheetQuery":{"description":"Query parameters accepted by the sheet endpoint.","type":"object","properties":{"rows":{"description":"Rows to fetch from the sheet, as a comma-separated list. Behavior is undefined if both `rows` and `after` are provided.","type":"string","pattern":"^\\d+(:\\d+)?(,\\d+(:\\d+)?)*$"},"limit":{"description":"Maximum number of rows to return. To paginate, provide the last returned row to the next request's `after` parameter.","type":["integer","null"],"format":"uint","minimum":0.0},"after":{"description":"Fetch rows after the specified row. Behavior is undefined if both `rows` and `after` are provided.","anyOf":[{"$ref":"#/components/schemas/RowSpecifier"},{"type":"null"}]}}},"RowSpecifier":{"type":"string","pattern":"^\\d+(:\\d+)?$"},"SheetResponse":{"description":"Response structure for the sheet endpoint.","type":"object","required":["rows","schema","version"],"properties":{"rows":{"description":"Array of rows retrieved by the query.","type":"array","items":{"$ref":"#/components/schemas/RowResult"}},"schema":{"description":"The canonical specifier for the schema used in this response.","type":"string"},"version":{"description":"The canonical specifier for the version used in this response.","type":"string"}}},"RowResult":{"type":"object","required":["fields","row_id"],"properties":{"row_id":{"description":"ID of this row.","type":"integer","format":"uint32","minimum":0.0},"subrow_id":{"description":"Subrow ID of this row, when relevant.","type":["integer","null"],"format":"uint16","minimum":0.0},"fields":{"description":"Field values for this row, according to the current schema and field filter.","$ref":"#/components/schemas/ValueString"},"transient":{"description":"Field values for this row's transient row, if any is present, according to the current schema and transient filter.","anyOf":[{"$ref":"#/components/schemas/ValueString"},{"type":"null"}]}}},"RowPath":{"description":"Path variables accepted by the row endpoint.","type":"object","required":["row","sheet"],"properties":{"sheet":{"description":"Name of the sheet to read.","type":"string"},"row":{"description":"Row to read.","$ref":"#/components/schemas/RowSpecifier"}}},"RowResponse":{"description":"Response structure for the row endpoint.","type":"object","required":["fields","row_id","schema","version"],"properties":{"schema":{"description":"The canonical specifier for the schema used in this response.","type":"string"},"version":{"description":"The canonical specifier for the version used in this response.","type":"string"},"row_id":{"description":"ID of this row.","type":"integer","format":"uint32","minimum":0.0},"subrow_id":{"description":"Subrow ID of this row, when relevant.","type":["integer","null"],"format":"uint16","minimum":0.0},"fields":{"description":"Field values for this row, according to the current schema and field filter.","$ref":"#/components/schemas/ValueString"},"transient":{"description":"Field values for this row's transient row, if any is present, according to the current schema and transient filter.","anyOf":[{"$ref":"#/components/schemas/ValueString"},{"type":"null"}]}}},"VersionsResponse":{"description":"Response structure for the version endpoint.","type":"object","required":["versions"],"properties":{"versions":{"description":"Array of versions available in the API.","type":"array","items":{"$ref":"#/components/schemas/VersionMetadata"}}}},"VersionMetadata":{"description":"Metadata about a single version supported by the API.","type":"object","required":["key","names"],"properties":{"key":{"description":"Canonical key for this version.","type":"string"},"names":{"description":"Names associated with this version. Version names specified here are accepted by the `version` query parameter throughout the API.","type":"array","items":{"type":"string"}}}}}},"tags":[{"name":"assets","description":"Endpoints for accessing game data on a file-by-file basis. Commonly useful for fetching icons or other textures to display on the web."},{"name":"search","description":"Endpoints for seaching and filtering the game's static relational data store."},{"name":"sheets","description":"Endpoints for reading data from the game's static relational data store."},{"name":"versions","description":"Endpoints for querying metadata about the versions recorded by the boilmaster system."}]}