XIVAPI

https://v2.xivapi.com/
Admin
XIVAPI is a comprehensive web API for Final Fantasy XIV game data, providing searchable access to...
Tokens:21,366
Snippets:125
Trust Score:8.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example JSON Data Structure - XIVAPI v2

Source: https://v2.xivapi.com/

This snippet demonstrates a typical JSON response structure from the XIVAPI v2, showing how game data like item names and descriptions are organized. It serves as an example of the data you can retrieve and process.

```json
{
  "row_id": 37362,
  "fields": {
    "Name": "Ironworks Tool Set",
    "Description": "A set of Garlond Ironworks' finest instruments."
  }
}
```

--------------------------------

### GET /version

Source: https://v2.xivapi.com/api/openapi.json

List versions understood by the API.

```APIDOC
## GET /version

### Description
List versions understood by the API.

### Method
GET

### Endpoint
/version

### Response
#### Success Response (200)
- **versions** (array) - List of available game versions.

#### Response Example
{
  "versions": [
    {"key": "f815390159effefd", "names": ["7.0"]},
    {"key": "2139246928a48a9a", "names": ["7.01", "latest"]}
  ]
}
```

--------------------------------

### Sheet Endpoint Examples

Source: https://v2.xivapi.com/docs/guides/sheets

Examples demonstrating the usage of sheet endpoints with different languages and field selections.

```APIDOC
## GET /api/sheet/{sheet}/{row}

### Description
Retrieves data for a specific row from a sheet, with options for language and field selection.

### Method
GET

### Endpoint
`/api/sheet/{sheet}/{row}`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies a subset of fields to include in the response. Supports dot notation for nested fields and array notation (e.g., `BaseParam[].Name`). Can also include decorators like `@lang(<lang>)`.
- **language** (string) - Optional - Specifies the language for localized strings. Defaults to 'en'.

### Request Example
```
GET /api/sheet/Item/42589?fields=Name,LevelEquip&language=en
```

### Response
#### Success Response (200)
- **fields** (object) - Contains the requested fields and their values.

#### Response Example
```json
{
  "fields": {
    "Name": "Angel Brush",
    "LevelEquip": 99
  }
}
```

## Language Parameter

### Description
Allows specifying the desired language for localized string data in the response.

### Method
GET

### Endpoint
`/api/sheet/{sheet}/{row}`

### Parameters
#### Query Parameters
- **language** (string) - Optional - The language code for the desired localization (e.g., 'en', 'ja', 'de', 'fr'). Defaults to 'en'.

### Request Example
```
GET /api/sheet/Item/42589?fields=Name&language=ja
```

### Response Example
```json
{
  "fields": {
    "Name": "天使の筆"
  }
}
```

## Fields Parameter

### Description
Filters the response to include only the specified fields. Supports dot notation for nested fields and array notation.

### Method
GET

### Endpoint
`/api/sheet/{sheet}/{row}`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - A comma-separated list of fields to retrieve. Use dot notation for nested fields (e.g., `ItemUICategory.Name`) and array notation for array fields (e.g., `BaseParam[].Name`).

### Request Example (Simple Fields)
```
GET /api/sheet/Item/42589?fields=Name,LevelEquip
```

### Response Example (Simple Fields)
```json
{
  "fields": {
    "Name": "Angel Brush",
    "LevelEquip": 99
  }
}
```

### Request Example (Nested Fields)
```
GET /api/sheet/Item/42589?fields=ItemUICategory.Name
```

### Response Example (Nested Fields)
```json
{
  "fields": {
    "ItemUICategory": {
      "fields": {
        "Name": "Pictomancer's Arm"
      }
    }
  }
}
```

### Request Example (Array Fields)
```
GET /api/sheet/Item/42589?fields=BaseParam[].Name
```

### Response Example (Array Fields)
```json
{
  "fields": {
    "BaseParam": [
      { "fields": { "Name": "Intelligence" } },
      { "fields": { "Name": "Vitality" } }
    ]
  }
}
```

## Decorators in Fields Parameter

### Description
Decorators can be appended to field names within the `fields` parameter to modify how data is retrieved or presented, such as specifying multiple languages in a single request.

### Method
GET

### Endpoint
`/api/sheet/{sheet}/{row}`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies fields and decorators. Use `@lang(<lang>)` to request specific language versions of a field.

### Request Example (Multiple Languages)
```
GET /api/sheet/Item/42589?fields=Name,Name@lang(ja)
```

### Response Example (Multiple Languages)
```json
{
  "fields": {
    "Name": "Angel Brush",
    "Name@lang(ja)": "天使の筆"
  }
}
```

### Request Example (Decorator on Nested Field)
```
GET /api/sheet/Item/42589?fields=ItemUICategory@lang(de).Name
```

### Response Example (Decorator on Nested Field)
```json
{
  "fields": {
    "ItemUICategory@lang(de)": {
      "fields": {
        "Name": "Hauptwaffe der Piktomanten"
      }
    }
  }
}
```
```

--------------------------------

### GET /asset

Source: https://v2.xivapi.com/api/openapi.json

Retrieves and converts a game asset from a specified path into a requested format.

```APIDOC
## GET /asset

### Description
Read an asset from the game at the specified path, converting it into a usable format. If no valid conversion exists, an error is returned.

### Method
GET

### Endpoint
/asset

### Parameters
#### Query Parameters
- **version** (string) - Optional - Game version to utilise for this query.
- **path** (string) - Required - Game path of the asset (e.g., ui/icon/051000/051474_hr1.tex).
- **format** (string) - Required - Format to convert the asset into (e.g., png).

### Response
#### Success Response (200)
- **byte stream** (binary) - The converted image data.

#### Response Example
[Binary Image Data]
```

--------------------------------

### GET /versions

Source: https://v2.xivapi.com/api/openapi.json

Retrieves a list of all versions supported by the API, including metadata such as canonical keys and associated names.

```APIDOC
## GET /versions

### Description
Returns an array of all versions available in the API, providing the metadata required to filter requests by specific game versions.

### Method
GET

### Endpoint
/versions

### Parameters
None

### Request Example
GET /versions

### Response
#### Success Response (200)
- **versions** (array) - List of version metadata objects.

#### Response Example
{
  "versions": [
    {
      "key": "latest",
      "names": ["latest", "6.5"]
    }
  ]
}
```

--------------------------------

### GET /search

Source: https://v2.xivapi.com/api/openapi.json

Executes a search query against game data sheets to fetch row information.

```APIDOC
## GET /search

### Description
Fetch information about rows and their related data that match the provided search query.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **version** (string) - Optional - Game version to utilise.
- **query** (string) - Optional - Search string to execute.
- **sheets** (string) - Optional - List of excel sheets to search.
- **cursor** (string) - Optional - Continuation token for pagination.
- **limit** (integer) - Optional - Maximum number of rows to return.

### Response
#### Success Response (200)
- **results** (object) - Search results containing rows and pagination metadata.

#### Response Example
{
  "results": [],
  "next": "uuid-token"
}
```

--------------------------------

### GET /sheet/{sheet}

Source: https://v2.xivapi.com/api/openapi.json

Retrieves data from a specific game data sheet with optional pagination and filtering.

```APIDOC
## GET /sheet/{sheet}

### Description
Fetches rows from a specified game data sheet. Supports fetching specific rows or paginating through the sheet.

### Method
GET

### Endpoint
/sheet/{sheet}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the sheet to read.

#### Query Parameters
- **rows** (string) - Optional - Comma-separated list of rows to fetch (e.g., "1,2,3").
- **limit** (integer) - Optional - Maximum number of rows to return.
- **after** (string) - Optional - Fetch rows after the specified row ID for pagination.

### Response
#### Success Response (200)
- **rows** (array) - Array of row objects retrieved.
- **schema** (string) - The canonical schema specifier.
- **version** (string) - The version of the data.

#### Response Example
{
  "rows": [{"row_id": 1, "fields": {}}],
  "schema": "v1",
  "version": "1.0.0"
}
```

--------------------------------

### GET /asset/map/{territory}/{index}

Source: https://v2.xivapi.com/api/openapi.json

Retrieves and composes a map from split source files based on territory and index.

```APIDOC
## GET /asset/map/{territory}/{index}

### Description
Retrieve the specified map, composing it from split source files if necessary.

### Method
GET

### Endpoint
/asset/map/{territory}/{index}

### Parameters
#### Path Parameters
- **territory** (string) - Required - Territory code (e.g., s1d1).
- **index** (string) - Required - Two-digit zero-padded index.

#### Query Parameters
- **version** (string) - Optional - Game version to utilise for this query.

### Response
#### Success Response (200)
- **byte stream** (binary) - The composed map image.

#### Response Example
[Binary Image Data]
```

--------------------------------

### Item Starting Weapon Off-Hand Data Structure (JSON)

Source: https://v2.xivapi.com/api/sheet/Item/42589

Details the specific data structure for an 'ItemStartingWeaponOffHand' within the v2_xivapi project. This includes properties like cast time, equip level, and various base parameters. It's crucial for defining the characteristics of off-hand weapons.

```json
{
  "value": 0,
  "sheet": "Item",
  "row_id": 0,
  "fields": {
    "AdditionalData": {"value": 0},
    "Adjective": 0,
    "AetherialReduce": 0,
    "AlwaysCollectable": false,
    "Article": 0,
    "BaseParam": [
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0}
    ],
    "BaseParamModifier": 0,
    "BaseParamSpecial": [
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0},
      {"value": 0}
    ],
    "BaseParamValue": [0, 0, 0, 0, 0, 0],
    "BaseParamValueSpecial": [0, 0, 0, 0, 0, 0],
    "Block": 0,
    "BlockRate": 0,
    "CanBeHq": false,
    "CastTimeSeconds": 2,
    "ClassJobCategory": {"value": 0},
    "ClassJobRepair": {"value": 0},
    "ClassJobUse": {"value": 0},
    "Cooldowns": 0,
    "DamageMag": 0,
    "DamagePhys": 0,
    "DefenseMag": 0,
    "DefensePhys": 0,
    "Delayms": 0,
    "Description": "",
    "Desynth": 0,
    "DyeCount": 0,
    "EquipRestriction": 0,
    "EquipSlotCategory": {"value": 0},
    "FilterGroup": 0,
    "GrandCompany": {"value": 0},
    "Icon": {"id": 0, "path": "ui/icon/000000/000000.tex", "path_hr1": "ui/icon/000000/000000_hr1.tex"},
    "IsAdvancedMeldingPermitted": false,
    "IsCollectable": false,
    "IsCrestWorthy": false,
    "IsGlamorous": false,
    "IsIndisposable": false,
    "IsPvP": false,
    "IsUnique": false,
    "IsUntradable": false,
    "ItemAction": {"value": 0},
    "ItemGlamour": {"value": 0},
    "ItemRepair": {"value": 0},
    "ItemSearchCategory": {"value": 0},
    "ItemSeries": {"value": 0},
    "ItemSortCategory": {"value": 2},
    "ItemSpecialBonus": {"value": 0},
    "ItemSpecialBonusParam": 0,
    "ItemUICategory": {"value": 0},
    "LevelEquip": 1,
    "LevelItem": {"value": 0},
    "Lot": false,
    "MateriaSlotCount": 0,
    "MaterializeType": 0,
    "ModelMain": 0,
    "ModelSub": 0,
    "Name": "",
    "Plural": "",
    "PossessivePronoun": 0,
    "PriceLow": 0,
    "PriceMid": 0,
    "Pronoun": 0,
    "Rarity": 0,
    "RequiredPvpRank": 0,
    "Singular": "",
    "StackSize": 1,
    "StartsWithVowel": 0,
    "SubStatCategory": 0,
    "Unknown0": 1,
    "Unknown2": 0,
    "Unknown3": 0,
    "Unknown4": 0
  }
}
```

--------------------------------

### Query multiple rows from a sheet

Source: https://v2.xivapi.com/docs/guides/sheets

Examples of retrieving multiple rows using default listing, pagination with after/limit parameters, and specific row ID selection.

```json
// /api/sheet/Item?fields=Name
{
  "rows": [
    { "row_id": 0, "fields": { "Name": "" } },
    { "row_id": 1, "fields": { "Name": "Gil" } }
  ]
}
```

```json
// /api/sheet/Item?fields=Name&after=1&limit=2
{
  "rows": [
    { "row_id": 2, "fields": { "Name": "Fire Shard" } },
    { "row_id": 3, "fields": { "Name": "Ice Shard" } }
  ]
}
```

```json
// /api/sheet/Item?fields=Name&rows=1,29,46
{
  "rows": [
    { "row_id": 1, "fields": { "Name": "Gil" } },
    { "row_id": 29, "fields": { "Name": "MGP" } },
    { "row_id": 46, "fields": { "Name": "Allagan Tomestone of Aesthetics" } }
  ]
}
```

--------------------------------

### GET /api/asset

Source: https://v2.xivapi.com/api/docs

Retrieves a game asset by its path and converts it to a specified format. Useful for fetching icons, textures, and other game files.

```APIDOC
## GET /api/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.

### Method
GET

### Endpoint
/api/asset

### Parameters
#### Query Parameters
- **version** (string | null) - Optional - Game version to utilise for this query.
- **path** (string) - Required - Game path of the asset to retrieve. Example: ui/icon/051000/051474_hr1.tex
- **format** (string) - Required - Format that the asset should be converted into. Allowed values: jpg, png, webp

### Request Example
```shell
curl 'https://v2.xivapi.com/api/asset?path=ui%2Ficon%2F051000%2F051474_hr1.tex&format=jpg'
```

### Response
#### Success Response (200)
- **byte stream** - The requested asset in the specified format (e.g., image/jpeg).

#### Response Example
(Binary data representing the image)
```

--------------------------------

### GET /api/search

Source: https://v2.xivapi.com/api/docs

Searches and filters the game's static relational data store. Allows for querying various game data points.

```APIDOC
## GET /api/search

### Description
Endpoints for searching and filtering the game's static relational data store.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **version** (string | null) - Optional - Game version to utilise for this query.

### Request Example
(No specific example provided in the source text for this endpoint's search parameters, but it would typically include search terms and filters.)

### Response
#### Success Response (200)
- **(Structure not detailed in source)** - Returns search results based on the query.

#### Response Example
(Structure not detailed in source)
```

--------------------------------

### GET /sheet/{sheet}/{row}

Source: https://v2.xivapi.com/api/openapi.json

Retrieves a single specific row from a game data sheet.

```APIDOC
## GET /sheet/{sheet}/{row}

### Description
Retrieves the details of a specific row within a given sheet.

### Method
GET

### Endpoint
/sheet/{sheet}/{row}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the sheet.
- **row** (string) - Required - The ID of the row to retrieve.

### Response
#### Success Response (200)
- **row_id** (integer) - The ID of the row.
- **fields** (object) - The data fields for this row.
- **schema** (string) - The canonical schema specifier.

#### Response Example
{
  "row_id": 101,
  "fields": {"Name": "Example Item"},
  "schema": "v1",
  "version": "1.0.0"
}
```

--------------------------------

### GET /api/asset/map/{territory}/{index}

Source: https://v2.xivapi.com/api/docs

Composes and retrieves a specified map, potentially combining split source files. Used for fetching in-game maps.

```APIDOC
## GET /api/asset/map/{territory}/{index}

### Description
Retrieve the specified map, composing it from split source files if necessary.

### Method
GET

### Endpoint
/api/asset/map/{territory}/{index}

### Parameters
#### Path Parameters
- **territory** (string) - Required - Territory of the map to be retrieved. Example: s1d1
- **index** (string) - Required - Index of the map within the territory. Example: 00

#### Query Parameters
- **version** (string | null) - Optional - Game version to utilise for this query.

### Request Example
```shell
curl https://v2.xivapi.com/api/asset/map/s1d1/00
```

### Response
#### Success Response (200)
- **byte stream** - The composed map image (e.g., image/jpeg).

#### Response Example
(Binary data representing the map image)
```

--------------------------------

### GET /sheet/{sheet}/{row}

Source: https://v2.xivapi.com/api/openapi.json

Read detailed, filterable information from a single sheet row and its related data.

```APIDOC
## GET /sheet/{sheet}/{row}

### Description
Read detailed, filterable information from a single sheet row and its related data.

### Method
GET

### Endpoint
/sheet/{sheet}/{row}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - Name of the sheet to read.
- **row** (string) - Required - Row to read.

#### Query Parameters
- **language** (string) - Optional - Language to use for data.
- **schema** (string) - Optional - Schema that row data should be read with.
- **fields** (string) - Optional - Data fields to read for selected rows.
- **transient** (string) - Optional - Data fields to read for selected rows' transient row.

### Response
#### Success Response (200)
- **fields** (object) - The requested row data.
- **row_id** (integer) - The ID of the row.
- **schema** (string) - The schema version used.
- **version** (string) - The data version.

#### Response Example
{
  "fields": {"FieldName": 14},
  "row_id": 1,
  "schema": "source@version",
  "version": "f815390159effefd"
}
```

--------------------------------

### Grouping Clauses with Parentheses for Complex Queries

Source: https://v2.xivapi.com/docs/guides/search

Demonstrates how to group clauses using parentheses to create more complex logical conditions. This example searches for Pictomancer actions available at level 80 or 90.

```json
// /api/search?sheets=Action&fields=Name,ClassJobLevel&query=+ClassJobCategory.PCT=true +(ClassJobLevel=80 ClassJobLevel=90)
{
  "results": [
    {
      "score": 2,
      "row_id": 34662,
      "fields": {
        "ClassJobLevel": 80,
        "Name": "Holy in White"
      }
    },
    {
      "score": 2,
      "row_id": 34663,
      "fields": {
        "ClassJobLevel": 90,
        "Name": "Comet in Black"
      }
    }
  ]
}
```

--------------------------------

### Querying Across Multiple Sheets

Source: https://v2.xivapi.com/docs/guides/search

Explains how to search across multiple data sheets simultaneously. Results from all sheets are merged and sorted by relevance. This example searches for 'rainbow' in both Action and Item sheets.

```json
// /api/search?sheets=Action,Item&fields=Name&query=Name~"rainbow"
{
  "results": [
    {
      "sheet": "Item",
      "row_id": 28928,
      "fields": {
        "Name": "Fae Rainbow"
      }
    },
    {
      "sheet": "Action",
      "row_id": 34688,
      "fields": {
        "Name": "Rainbow Drip"
      }
    }
    // ...
  ]
}
```

--------------------------------

### GET /api/sheet/{sheet}

Source: https://v2.xivapi.com/docs/guides/sheets

Retrieves multiple rows from a sheet with support for pagination, limits, and specific row ID filtering.

```APIDOC
## GET /api/sheet/{sheet}

### Description
Retrieves multiple rows from a sheet. Supports pagination via `after` and `limit`, or specific row selection via `rows`.

### Method
GET

### Endpoint
/api/sheet/{sheet}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the data sheet.

#### Query Parameters
- **fields** (string) - Optional - Fields to include in the response.
- **after** (integer) - Optional - Skip rows with ID less than or equal to this value.
- **limit** (integer) - Optional - Maximum number of rows to return.
- **rows** (string) - Optional - Comma-separated list of specific row IDs to retrieve.

### Response
#### Success Response (200)
- **rows** (array) - A list of row objects containing row_id and fields.

#### Response Example
{
  "rows": [
    { "row_id": 1, "fields": { "Name": "Gil" } },
    { "row_id": 2, "fields": { "Name": "Fire Shard" } }
  ]
}
```

--------------------------------

### Filtering Search Results with Mandatory Clauses

Source: https://v2.xivapi.com/docs/guides/search

Shows how to use the '+' prefix to enforce that specific clauses must match, ensuring only relevant results are returned. This example filters for actions usable by Pictomancers at level 92.

```json
// /api/search?sheets=Action&fields=Name&query=+ClassJobCategory.PCT=true +ClassJobLevel=92
{
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    }
  ]
}
```

--------------------------------

### GET /api/sheet/{sheet}/{id}

Source: https://v2.xivapi.com/docs/guides/pinning

Retrieves specific sheet data with support for versioning and schema pinning to ensure consistent data structures.

```APIDOC
## GET /api/sheet/{sheet}/{id}

### Description
Fetches data from a specific game sheet. Supports versioning to view historical data and schema pinning to maintain consistent field mappings.

### Method
GET

### Endpoint
/api/sheet/{sheet}/{id}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the game sheet to query.
- **id** (integer) - Required - The unique identifier for the row in the sheet.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to return.
- **version** (string) - Optional - The game version to query (e.g., '7.0', '7.1'). Defaults to 'latest'.
- **schema** (string) - Optional - The schema identifier to use for interpreting sheet data (e.g., 'exdschema@2:rev:<revision>').

### Request Example
GET /api/sheet/Action/27?fields=Range&version=7.1

### Response
#### Success Response (200)
- **fields** (object) - The requested data fields.
- **schema** (string) - The canonical schema identifier used for the request.

#### Response Example
{
  "schema": "exdschema@2:rev:c44cfd270a72248293e242b4950b2ddeff9e49f2",
  "fields": {
    "Range": 20
  }
}
```

--------------------------------

### Filtering Search Results with Exclusive Clauses

Source: https://v2.xivapi.com/docs/guides/search

Illustrates using the '-' prefix to exclude results that match a specific clause. This example finds actions for Warriors that are not available before level 96.

```json
// /api/search?sheets=Action&fields=Name,ClassJobLevel&query=ClassJobCategory.WAR=true -ClassJobLevel<96
{
  "results": [
    {
      "row_id": 36924,
      "fields": {
        "ClassJobLevel": 96,
        "Name": "Primal Wrath"
      }
    },
    {
      "row_id": 36925,
      "fields": {
        "ClassJobLevel": 100,
        "Name": "Primal Ruination"
      }
    }
  ]
}
```

--------------------------------

### Get Sheet Rows

Source: https://v2.xivapi.com/api/openapi.json

Retrieve specific rows or a range of rows from a given sheet.

```APIDOC
## GET /sheet/{sheet}

### Description
Retrieve specific rows or a range of rows from a given sheet.

### Method
GET

### Endpoint
/sheet/{sheet}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the sheet to read.

#### Query Parameters
- **rows** (string) - Optional - Comma-separated list of rows to fetch. Behavior is undefined if both `rows` and `after` are provided.
- **limit** (integer, null) - Optional - Maximum number of rows to return. To paginate, provide the last returned row to the next request's `after` parameter.
- **after** (RowSpecifier, null) - Optional - Fetch rows after the specified row. Behavior is undefined if both `rows` and `after` are provided.
- **language** (SchemaLanguage, null) - Optional - Language to use for data with no language otherwise specified in the fields filter.
- **schema** (SchemaSpecifier, null) - Optional - Schema that row data should be read with.
- **fields** (FilterString, null) - Optional - Data fields to read for selected rows.
- **transient** (FilterString, null) - Optional - Data fields to read for selected rows' transient row, if any is present.

### Response
#### Success Response (200)
- **rows** (array) - A list of rows from the sheet.
  - **fields** (object) - The data fields for the row.
  - **row_id** (integer) - The ID of the row.
  - **version** (string) - The game version the data is from.

#### Response Example
```json
{
  "rows": [
    {
      "fields": {
        "FieldName": 14
      },
      "row_id": 1,
      "version": "f815390159effefd"
    }
  ]
}
```

#### Error Response (default)
- **code** (integer) - The error code.
- **message** (string) - A message describing the error.

#### Error Response Example
```json
{
  "code": 400,
  "message": "invalid request: example error response"
}
```
```

--------------------------------

### Fetch Game Asset by Path and Format

Source: https://v2.xivapi.com/docs/guides/assets

Retrieve a game asset by specifying its path within the game files and the desired output format. This endpoint supports game version pinning and utilizes caching with ETag and If-None-Match headers for efficient delivery. Ensure the path/format combination is sensible to avoid errors.

```http
GET /api/asset?path=ui/loadingimage/-nowloading_base01_hr1.tex&format=png
```

--------------------------------

### Transform fields using @as decorator

Source: https://v2.xivapi.com/docs/guides/sheets

Demonstrates how to use the @as(raw) decorator to retrieve unparsed data and the @as(html) decorator to convert rich text into HTML fragments.

```json
// /api/sheet/Item/42589?fields=ItemUICategory,ItemUICategory@as(raw)
{
  "fields": {
    "ItemUICategory": {
      "value": 111
    },
    "ItemUICategory@as(raw)": 111
  }
}
```

```json
// /api/sheet/Item/44104?fields=Description,Description@as(html)
{
  "fields": {
    "Description": "Warm flour tortillas...",
    "Description@as(html)": "Warm flour tortillas...<br><span style=\"color:rgba(0,204,34,1);\">EXP Bonus:</span>..."
  }
}
```

--------------------------------

### Filter syntax migration for XIVAPI

Source: https://v2.xivapi.com/docs/migrate

Demonstrates the change in syntax for filtering array fields between v1 and v2. The v1 dot-notation is replaced by bracket notation in v2.

```text
// v1
columns=Array.*.Field
// v2
fields=Array[].Field
```

--------------------------------

### Fetch Assets API

Source: https://v2.xivapi.com/docs/guides/assets

Retrieve game assets by their path and desired format. Supports game version pinning and utilizes caching with ETag headers.

```APIDOC
## GET /api/asset

### Description
Fetches a game asset, converting it to the specified format. Supports game version pinning and respects caching headers.

### Method
GET

### Endpoint
/api/asset

### Query Parameters
- **path** (string) - Required - The path to the asset within the game files.
- **format** (string) - Required - The desired output format for the asset (e.g., png, jpg, json).
- **game_version** (string) - Optional - Specifies the game version to retrieve the asset from.

### Request Example
```
GET /api/asset?path=ui/loadingimage/-nowloading_base01_hr1.tex&format=png
```

### Response
#### Success Response (200)
- **asset_data** (binary/string) - The converted asset file content.
- **ETag** (string) - An ETag header for caching purposes.

#### Response Example
(Binary data for the requested asset)
```

--------------------------------

### GET /api/sheet/{sheet}/{row}

Source: https://v2.xivapi.com/docs/guides/sheets

Retrieves a single row from a specific data sheet with optional field transformations.

```APIDOC
## GET /api/sheet/{sheet}/{row}

### Description
Fetches a single row from a specified sheet. Supports field filtering and transformations like `@as(raw)` for raw data or `@as(html)` for formatted text.

### Method
GET

### Endpoint
/api/sheet/{sheet}/{row}

### Parameters
#### Path Parameters
- **sheet** (string) - Required - The name of the data sheet.
- **row** (integer) - Required - The ID of the row to retrieve.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to return, supports `@as` decorators.
- **transient** (string) - Optional - Controls inclusion of related transient sheet data.

### Response
#### Success Response (200)
- **fields** (object) - The requested data fields.

#### Response Example
{
  "fields": {
    "Name": "Example Item",
    "Description@as(html)": "<p>Example description</p>"
  }
}
```

--------------------------------

### GET /api/search

Source: https://v2.xivapi.com/docs/guides/search

Search for records across game sheets with support for query filtering, field selection, and pagination.

```APIDOC
## GET /api/search

### Description
Searches through game data sheets based on provided query parameters. Supports pagination via a cursor system for large datasets.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **query** (string) - Optional - The search filter string (e.g., Name~"rainbow").
- **limit** (integer) - Optional - The maximum number of results to return per page.
- **fields** (string) - Optional - Comma-separated list of fields to return.
- **sheets** (string) - Optional - The sheet(s) to search within.
- **cursor** (string) - Optional - The pagination token to fetch the next set of results.

### Request Example
/api/search?fields=Name&sheets=Action&query=Name~"rainbow"&limit=2

### Response
#### Success Response (200)
- **next** (string) - The cursor token for the next page of results.
- **results** (array) - A list of objects containing row_id and requested fields.

#### Response Example
{
  "next": "4bce9ed3-74d7-4d4c-940f-4a918d204a58",
  "results": [
    { "row_id": 34688, "fields": { "Name": "Rainbow Drip" } },
    { "row_id": 21474, "fields": { "Name": "Lunar Rainbow" } }
  ]
}
```

--------------------------------

### Pinning Game Versions for API Data

Source: https://v2.xivapi.com/docs/guides/pinning

Demonstrates how to retrieve specific historical data for game actions by providing a version parameter. This ensures that API responses remain consistent even after game updates modify data structures.

```HTTP
// /api/sheet/Action/27?fields=Range&version=7.0
{ "fields": { "Range": 10 } }

// /api/sheet/Action/27?fields=Range&version=7.1
{ "fields": { "Range": 20 } }
```

--------------------------------

### Search Endpoint

Source: https://v2.xivapi.com/api/openapi.json

Allows searching for game data using various query parameters. Supports filtering by query string, specific sheets, and pagination via cursors.

```APIDOC
## GET /websites/v2_xivapi/search

### Description
Searches for game data based on provided query parameters. Supports filtering by query string, specific sheets, and pagination using a cursor.

### Method
GET

### Endpoint
/websites/v2_xivapi/search

### Parameters
#### Query Parameters
- **query** (string) - Optional - The search query to execute. Must be specified if not querying a cursor. Special characters must be escaped.
- **sheets** (string) - Optional - A list of Excel sheets to run the query against. At least one must be specified if not querying a cursor.
- **cursor** (uuid) - Optional - Continuation token to retrieve further results from a prior search request. Takes priority over `query`.
- **limit** (uint) - Optional - Maximum number of rows to return. Use with `cursor` for pagination.

### Request Example
```json
{
  "query": "Name="Example Item"",
  "sheets": "Items",
  "limit": 100
}
```

### Response
#### Success Response (200)
- **next** (string) - The cursor for the next page of results.
- **results** (array) - An array of search results.

#### Response Example
```json
{
  "next": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "results": [
    {
      "id": 12345,
      "name": "Example Item"
    }
  ]
}
```
```

--------------------------------

### Search using comparison and partial match operators

Source: https://v2.xivapi.com/docs/guides/search

Demonstrates the use of advanced operators like partial string matching (~) and numeric comparisons (>, >=, <, <=) to filter results beyond exact equality.

```http
// /api/search?sheets=Action&fields=Name&query=Name~"rainbow"
{
  "results": [
    { "row_id": 34688, "fields": { "Name": "Rainbow Drip" } },
    { "row_id": 21474, "fields": { "Name": "Lunar Rainbow" } }
  ]
}
```

```http
// /api/search?sheets=Action&fields=Name,Recast100ms&query=Recast100ms>3000
{
  "results": [
    { "row_id": 6, "fields": { "Name": "Return", "Recast100ms": 9000 } },
    { "row_id": 30, "fields": { "Name": "Hallowed Ground", "Recast100ms": 4200 } }
  ]
}
```

--------------------------------

### List Sheets

Source: https://v2.xivapi.com/api/openapi.json

List all available sheets that can be queried via the API.

```APIDOC
## GET /sheet

### Description
List all available sheets that can be queried via the API.

### Method
GET

### Endpoint
/sheet

### Parameters
#### Query Parameters
- **version** (string, null) - Optional - The game version to use for the query.

### Response
#### Success Response (200)
- **sheets** (array) - A list of sheet names.
  - **name** (string) - The name of the sheet.

#### Response Example
```json
{
  "sheets": [
    {
      "name": "Action"
    },
    {
      "name": "Item"
    },
    {
      "name": "Status"
    }
  ]
}
```

#### Error Response (default)
- **code** (integer) - The error code.
- **message** (string) - A message describing the error.

#### Error Response Example
```json
{
  "code": 400,
  "message": "invalid request: example error response"
}
```
```

--------------------------------

### Search for sheet rows using query clauses

Source: https://v2.xivapi.com/docs/guides/search

Demonstrates how to perform basic searches using exact equality operators on specific fields. The query parameter filters the results based on the provided sheet and field criteria.

```http
// /api/search?sheets=Action&fields=Name&query=Name="Rainbow Drip"
{
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    }
  ]
}
```

--------------------------------

### Localize Sheet Data via Language Parameter

Source: https://v2.xivapi.com/docs/guides/sheets

Demonstrates how to retrieve localized strings for a specific sheet row by appending the language parameter to the API request.

```HTTP
// /api/sheet/Item/42589?fields=Name&language=ja
{ "fields": { "Name": "天使の筆" } }
// /api/sheet/Item/42589?fields=Name&language=en
{ "fields": { "Name": "Angel Brush" } }
// /api/sheet/Item/42589?fields=Name&language=de
{ "fields": { "Name": "Engelspinsel" } }
// /api/sheet/Item/42589?fields=Name&language=fr
{ "fields": { "Name": "Pinceau angélique" } }
```

--------------------------------

### Item Data Structure (JSON)

Source: https://v2.xivapi.com/api/sheet/Item/42589

Represents the data structure for an item in the v2_xivapi project. It includes various properties related to the item's attributes, usage, and appearance. This structure is fundamental for managing and displaying item information.

```json
{
  "LevelItem": {"value": 0},
  "Lot": false,
  "MateriaSlotCount": 0,
  "MaterializeType": 0,
  "ModelMain": 0,
  "ModelSub": 0,
  "Name": "",
  "Plural": "",
  "PossessivePronoun": 0,
  "PriceLow": 0,
  "PriceMid": 0,
  "Pronoun": 0,
  "Rarity": 0,
  "RequiredPvpRank": 0,
  "Singular": "",
  "StackSize": 1,
  "StartsWithVowel": 0,
  "SubStatCategory": 0,
  "Unknown0": 1,
  "Unknown2": 0,
  "Unknown3": 0,
  "Unknown4": 0
}
```

--------------------------------

### Pinning EXDSchema Revisions

Source: https://v2.xivapi.com/docs/guides/pinning

Shows how to use the schema parameter with EXDSchema git revisions to pin data structures. This is useful for maintaining compatibility when field names or mappings change between schema versions.

```HTTP
// /api/sheet/WorldDCGroupType/9?fields=Unknown0,NeolobbyId&schema=exdschema@2:rev:c44cfd2
{
  "schema": "exdschema@2:rev:c44cfd270a72248293e242b4950b2ddeff9e49f2",
  "fields": { "NeolobbyId": 9 }
}

// /api/sheet/WorldDCGroupType/9?fields=Unknown0,NeolobbyId&schema=exdschema@2:rev:22f45f4
{
  "schema": "exdschema@2:rev:22f45f4d6aab0c8722f5c0a6eabceb1e2a13c12c",
  "fields": { "Unknown0": 9 }
}
```

--------------------------------

### Search API - Basic Querying and Relevance

Source: https://v2.xivapi.com/docs/guides/search

Demonstrates how to perform a basic search with multiple clauses and explains the relevance scoring mechanism. Results are sorted by how many clauses they match, with the score indicated.

```APIDOC
## GET /api/search

### Description
Searches across specified sheets for items matching one or more query clauses. Results are ranked by relevance, with a `score` field indicating how many clauses were matched.

### Method
GET

### Endpoint
/api/search

### Query Parameters
- **sheets** (string) - Required - Comma-separated list of sheets to search within.
- **fields** (string) - Optional - Comma-separated list of fields to return for each result.
- **query** (string) - Required - The search query string, defining clauses and their conditions.

### Request Example
```
/api/search?sheets=Action&fields=ClassJobLevel,Name&query=ClassJobLevel=92 Name="Rainbow Drip"
```

### Response
#### Success Response (200)
- **results** (array) - An array of search results.
  - **score** (integer) - The relevance score of the result (number of matched clauses).
  - **row_id** (integer) - The unique ID of the row in its sheet.
  - **fields** (object) - An object containing the requested fields for the result.

#### Response Example
```json
{
  "results": [
    {
      "score": 2,
      "row_id": 34688,
      "fields": {
        "ClassJobLevel": 92,
        "Name": "Rainbow Drip"
      }
    },
    {
      "score": 1,
      "row_id": 34644,
      "fields": {
        "ClassJobLevel": 92,
        "Name": "Uncoiled Twinfang"
      }
    }
  ]
}
```
```

--------------------------------

### Retrieve transient sheet data

Source: https://v2.xivapi.com/docs/guides/sheets

Shows how to use the transient parameter to include related data from secondary sheets in the API response.

```json
// /api/sheet/Action/34684?transient=Description@as(html)
{
  "fields": {},
  "transient": {
    "Description@as(html)": "Quickly dash 15 yalms forward.<br><span style=\"color:rgba(0,204,34,1);\">Duration: </span>5s"
  }
}
```

--------------------------------

### Compose Maps API

Source: https://v2.xivapi.com/docs/guides/assets

Composes map assets that are split across multiple files into a single image. Automatically merges map files when requested.

```APIDOC
## GET /api/asset/map/{mapId}/{mapFilename}

### Description
Composes and retrieves map assets that are split across multiple files. This endpoint automatically merges the necessary files into a single image.

### Method
GET

### Endpoint
/api/asset/map/{mapId}/{mapFilename}

### Path Parameters
- **mapId** (string) - Required - The ID of the map.
- **mapFilename** (string) - Required - The filename component of the map asset.

### Query Parameters
- **game_version** (string) - Optional - Specifies the game version to retrieve the map from.

### Request Example
```
GET /api/asset/map/s1d1/00
```

### Response
#### Success Response (200)
- **map_image_data** (binary) - The composed map image data.
- **ETag** (string) - An ETag header for caching purposes.

#### Response Example
(Binary image data for the composed map)
```
Tokens:
Raw