{"openapi":"3.1.0","info":{"title":"boilmaster","version":"1-5088e3b"},"paths":{"/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":"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.","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"}}}}}}}},"components":{"schemas":{"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","tc","ko"]},"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"},"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},"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"}]}}}}},"tags":[{"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."}]}