# Free Fire Community API - Version: 2.0 - OpenAPI: 3.0.3 - Contact: https://developers.freefirecommunity.com/en/contact, developers@freefirecommunity.com ## Base URLs - `https://developers.freefirecommunity.com/api/v1`: Production API server (version 1) ## Security schemes - `ApiKeyAuth`: API key in header: x-api-key. Your API key, sent in the `x-api-key` header. **Recommended.** Create a key on the [Developer Platform](https://developers.freefirecommunity.com/). - Keep the key server-side. Never ship it in client-side code. - Rotate it immediately if it is compromised. - `ApiKeyQueryAuth`: API key in query: key. Your API key, sent as the `key` query parameter. Convenient for quick tests, but the key can appear in URLs and logs. Prefer the `x-api-key` header in production. Default requirement for all endpoints: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key). The Free Fire Community API gives developers REST access to Free Fire player profiles, career statistics, ban status, guild details, Craftland maps, wishlists and in-game assets across the SG, IND and BR regions. ## Quick start 1. Create an API key on the [Developer Platform](https://developers.freefirecommunity.com/). 2. Call an endpoint from your **server** with the `x-api-key` header and a custom `User-Agent` header (required, see **Required User-Agent** below). ```bash curl "https://developers.freefirecommunity.com/api/v1/info?region=ind&uid=665951869" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ## Features - Player profile data, rankings and clan membership - Career statistics for Solo, Duo and Squad modes - Ban status checking - Guild (clan) information - Craftland map details - Player wishlists - In-game images and icons - Multi-region support: SG, IND and BR - Server-side caching for fast responses ## Authentication Authenticate every request with your API key, using either method: - **Header (recommended):** `x-api-key: your_api_key_here`. The key stays out of URLs and logs. - **Query parameter:** `?key=your_api_key_here`. Convenient for quick tests, but less secure. Keys start with `ffc_` and are at least 30 characters long. A missing key returns `AUTH_001`, and an invalid key returns `AUTH_002`. ## Required User-Agent Every request passes through an edge firewall **before** authentication. Server-side integrations and bots must send a custom `User-Agent` header, or they are blocked with a `403` (or `429`) and an `FW_00x` code before the API key is even checked. **Rules** - Send a `User-Agent` of at least 10 characters. - It must **not** contain HTTP library or automation names anywhere in the string, for example `curl`, `python`, `requests`, `axios`, `node-fetch`, `Go-http-client`, `okhttp`, `java`, `wget`, `bot`, `scrapy`, `puppeteer`, `playwright`, `selenium`, `postman`, `insomnia` or `httpie`. Matching is case-insensitive and substring-based, so `bot` matches even inside a URL such as `github.com/user/my-bot`. - The default User-Agents of `fetch`/undici, Python `requests`, Go `net/http` and `curl` are blocked. Override the header explicitly. - Recommended format: `AppName/1.0 (+https://your-site-or-repo)`. **Firewall codes** - `FW_001` (403): `User-Agent` missing or shorter than 10 characters. - `FW_002` (403): `User-Agent` matches a blocked library or bot pattern. - `FW_003` (403): `User-Agent` reports a very old browser version. - `FW_004` (429): too many requests from one IP (edge rate limit). Honor `Retry-After`. A `403` with an `FW_` code is a firewall or User-Agent problem, not an API key, plan or region issue. The `region` parameter never affects the firewall or authorization. ## Regions Most endpoints accept a `region` query parameter: - `sg`: Singapore region. Covers `SG`, `ID`, `ME`, `VN`, `TH`, `CIS`, `EU`, `TW`, `MY`, `PK`, `BD`. - `ind`: India region. Covers India only. - `br`: Brazil region. Covers `BR`, `US`, `NA`, `LATAM`. ## Rate limits and quota Limits depend on your plan: - **Trial:** playground only. No API key and no production usage. - **Trial Pass:** 500 total requests (one-time), 20 requests/minute, 100 requests/hour. - **Beginner:** 5,000 requests/month, 30 requests/minute, 500 requests/hour. - **Developer:** 15,000 requests/month, 60 requests/minute, 2,000 requests/hour. - **Pro:** 50,000 requests/month, 120 requests/minute, 6,000 requests/hour. - **Enterprise:** 100,000+ requests/month, custom rate limits. Top-up credits and upgrade carry-over credits are added on top of your monthly quota. **Quota cost.** Most endpoints use **1 unit** of monthly quota per request. `/stats` uses **2 units**. The cost is returned in the `X-Quota-Cost` response header. Per-minute and per-hour burst limits always count each request as 1. **Per-IP abuse guard.** In addition to plan limits, requests are counted per IP address over a 5-minute window. Free and trial plans allow 30 requests per window. Paid plans allow at least `max(30, per-minute limit × 5)`. Exceeding it returns `429` with `code: RATE_001` and `type: ip-based`. **Response headers.** Successful responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (per-minute window), `X-RateLimit-Hour-Limit`, `X-RateLimit-Hour-Remaining` and `X-RateLimit-Hour-Reset` (per-hour window), plus `X-Quota-Cost`, `X-Response-Time`, `X-API-Version` and `X-Cache` (`HIT` or `MISS`). ## Caching Upstream data is cached server-side. Cached responses return `X-Cache: HIT` and `X-Cache-TTL`, and they still count against your quota and rate limits. - `/info`, `/stats`, `/guild`: 5 minutes - `/bancheck`, `/wishlist`: 10 minutes - `/craftland`: 15 minutes - `/image`: 1 hour ## Errors Errors are returned as JSON with a stable `code`: - `AUTH_001`: missing API key - `AUTH_002`: invalid API key - `AUTH_003`: inactive API key - `AUTH_004`: expired API key - `RATE_001`: rate limit exceeded (per-minute, per-hour or per-IP) - `QUOTA_001`: monthly quota exhausted - `PARAM_001`: missing parameter - `RES_001`: resource not found - `SYS_001`: internal error - `SYS_002`: service unavailable or data provider failure - `SYS_003`: data provider timeout - `FW_001` to `FW_004`: edge firewall (see **Required User-Agent** above) ## Security and privacy - Make API requests from your server to protect your API key. - Never expose your API key in client-side code. Rotate it if it is compromised. - We do not store or share personal player data. - All data comes from publicly available information. ## Disclaimer This API and the Free Fire Community platform are **not affiliated with, endorsed by, or connected to Garena International or Free Fire**. This is an independent, community-driven project. All trademarks, game content and assets belong to their respective owners. ## Support and community - **Developer Portal:** [developers.freefirecommunity.com](https://developers.freefirecommunity.com/) - **Documentation:** [docs.freefirecommunity.com](https://docs.freefirecommunity.com/) - **API Status:** [status page](https://stats.uptimerobot.com/pB5twu5M3x/801663024) - **Email:** [developers@freefirecommunity.com](mailto:developers@freefirecommunity.com) ## API reference ### Player Information Player profile data, rankings, clan and account information. #### `GET /info`: Get player information - Anchor: `#operation-getplayerinfo` - Operation ID: `getPlayerInfo` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns a player's profile: account details, rank, badges, clan membership, pet, equipped items, credit score and season data. - Basic account details (nickname, level, rank, likes) - Badge and banner information - Clan (guild) membership details - Pet information and skills - Equipped items and skins - Credit score and diamond cost Use the `region` that matches the player's account region. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `region` | query | string | no | Region of the player's account. Recommended on every request. - `sg`: Singapore region (SG, ID, ME, VN, TH, CIS, EU, TW, MY, PK, BD) - `ind`: India region (India only) - `br`: Brazil region (BR, US, NA, LATAM) When omitted, `/stats` and `/wishlist` default to `ind` and `/craftland` defaults to `sg`. `/info` forwards the value to the data provider as-is. Allowed: `sg`, `ind`, `br`. Example: `"ind"` | | `uid` | query | string | yes | The player's unique User ID (5 to 15 digits). Pattern: `^\d{5,15}$`. Example: `"665951869"` | **Responses** - `200`: Player information retrieved. (`application/json`) Type: `PlayerInfoResponse` - `basicInfo` (PlayerBasicInfo, required): Core account and ranking information. - `accountId` (string): Player account ID. - `nickname` (string): Player display name. - `level` (integer): Account level. - `rank` (integer): Current Battle Royale rank. - `maxRank` (integer): Highest Battle Royale rank reached. - `csRank` (integer): Current Clash Squad rank. - `csMaxRank` (integer): Highest Clash Squad rank reached. - `rankingPoints` (integer): Current ranking points. - `region` (string): Account region. - `seasonId` (integer): Current season ID. - `liked` (integer): Number of likes the profile has received. - `title` (string): Equipped title. - `badgeId` (string): Equipped badge ID. - `bannerId` (string): Equipped banner ID. - `captainBasicInfo` (PlayerBasicInfo): Core account and ranking information. - `accountId` (string): Player account ID. - `nickname` (string): Player display name. - `level` (integer): Account level. - `rank` (integer): Current Battle Royale rank. - `maxRank` (integer): Highest Battle Royale rank reached. - `csRank` (integer): Current Clash Squad rank. - `csMaxRank` (integer): Highest Clash Squad rank reached. - `rankingPoints` (integer): Current ranking points. - `region` (string): Account region. - `seasonId` (integer): Current season ID. - `liked` (integer): Number of likes the profile has received. - `title` (string): Equipped title. - `badgeId` (string): Equipped badge ID. - `bannerId` (string): Equipped banner ID. - `clanBasicInfo` (ClanBasicInfo): Clan (guild) the player belongs to. - `clanId` (string): Clan ID. - `clanName` (string): Clan name. - `captainId` (string): Account ID of the clan captain. - `clanLevel` (integer): Clan level. - `memberNum` (integer): Current number of members. - `capacity` (integer): Maximum number of members. - `petInfo` (PetInfo): The player's pet. - `id` (string): Pet ID. - `skinId` (string): Equipped pet skin ID. - `selectedSkillId` (string): Selected pet skill ID. - `level` (integer): Pet level. - `exp` (integer): Pet experience points. - `isSelected` (boolean): Whether this pet is currently equipped. - `creditScoreInfo` (CreditScoreInfo): Account credit score and reward state. - `creditScore` (integer): Current credit score. - `rewardStartAt` (string): Reward period start. - `rewardEndAt` (string): Reward period end. - `rewardState` (integer): Reward state code. - `rewardType` (integer): Reward type code. - `diamondCostRes` (DiamondCostResponse): Diamond spending summary. - `diamondCost` (integer): Diamonds spent. - `profileInfo` (ProfileInfo): Equipped avatar, clothes and skills. - `avatarId` (string): Equipped avatar ID. - `clothes` (string[]): IDs of equipped clothing items. - `equipedSkills` (object[]): Equipped character skills. - `isSelected` (boolean): Whether this profile setup is currently selected. - `isSelectedAwaken` (boolean): Whether the awakened variant is selected. - `socialInfo` (SocialInfo): Social profile details. - `accountId` (string): Player account ID. - `signature` (string): Profile signature text. ```json { "basicInfo": { "accountId": "665951869", "nickname": "FFC•ASHQKING", "level": 61, "rank": 306, "liked": 4902, "region": "IND" }, "captainBasicInfo": { "accountId": "973498167", "nickname": "Captain", "level": 72, "rank": 326, "liked": 18320, "region": "IND" }, "clanBasicInfo": { "clanName": "ƝEOƝ»Ᏻᴀɴɢ×͜×", "memberNum": 49, "clanLevel": 5, "capacity": 50 }, "creditScoreInfo": { "creditScore": 100, "rewardState": 1 }, "diamondCostRes": { "diamondCost": 390 }, "petInfo": { "id": "1300000119", "level": 5 }, "profileInfo": { "avatarId": "101000007" }, "socialInfo": { "accountId": "665951869", "signature": "I love free fire" } } ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `500`: Internal server error (`SYS_001`). Include the `requestId` when contacting support. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/info?region=ind&uid=665951869" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Player Statistics Career gameplay statistics for Solo, Duo and Squad modes. #### `GET /stats`: Get player statistics - Anchor: `#operation-getplayerstats` - Operation ID: `getPlayerStats` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns a player's all-time career statistics for each Battle Royale mode (Solo, Duo, Squad). - Total games played, wins and eliminations - Highest eliminations in a single match - Headshot statistics - Vehicle eliminations - Knockdowns and revives (Duo and Squad) - Top placement counts (top 3, top 5, top 10) **Quota cost:** each request uses **2 units** of monthly quota (reported in the `X-Quota-Cost` header). Burst limits still count it as 1. **Region:** optional. Defaults to `ind` when omitted. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `region` | query | string | no | Region of the player's account. Recommended on every request. - `sg`: Singapore region (SG, ID, ME, VN, TH, CIS, EU, TW, MY, PK, BD) - `ind`: India region (India only) - `br`: Brazil region (BR, US, NA, LATAM) When omitted, `/stats` and `/wishlist` default to `ind` and `/craftland` defaults to `sg`. `/info` forwards the value to the data provider as-is. Allowed: `sg`, `ind`, `br`. Example: `"ind"` | | `uid` | query | string | yes | The player's unique User ID (5 to 15 digits). Pattern: `^\d{5,15}$`. Example: `"665951869"` | **Responses** - `200`: Player statistics retrieved. (`application/json`) Type: `PlayerStatsResponse` - `brCareer_solo` (object): Solo mode career statistics. - `brCareer_duo` (object): Duo mode career statistics. - `brCareer_squad` (object): Squad mode career statistics. ```json { "brCareer_solo": {}, "brCareer_duo": {}, "brCareer_squad": {} } ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `500`: Internal server error (`SYS_001`). Include the `requestId` when contacting support. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `502`: The data provider failed or returned a non-JSON response (`SYS_002`). Includes `upstreamStatus` when available. Safe to retry. `Retry-After` is 5 seconds on connection failures. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `504`: The data provider did not respond within 8 seconds (`SYS_003`). Retry after the `Retry-After` interval (5 seconds). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/stats?region=ind&uid=665951869" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Player Ban Check Check whether a player account is banned or has an active ban period. #### `GET /bancheck`: Check player ban status - Anchor: `#operation-checkplayerbanstatus` - Operation ID: `checkPlayerBanStatus` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Checks whether a Free Fire player account is currently banned or has an active ban period. **Note:** the upstream check is currently always performed with `lang=en`, so the `lang` parameter does not change the response language yet. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `uid` | query | string | yes | The player's unique User ID (5 to 15 digits). Pattern: `^\d{5,15}$`. Example: `"665951869"` | | `lang` | query | string | no | Language for the response. Allowed: `en`, `ar`, `es`, `id`, `pt`, `ru`, `vi`. Default: `"en"`. Example: `"en"` | **Responses** - `200`: Ban check completed. (`application/json`) Type: `BanCheckResponse` - `status` (string): Status of the ban check request. - `data` (object) - `is_banned` (integer): `1` if the account is banned, otherwise `0`. Allowed: `0`, `1` - `period` (integer): Ban period reported by the data provider. ```json { "status": "string", "data": { "is_banned": 0, "period": 123 } } ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/bancheck?uid=665951869&lang=en" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Player Wishlist Items on a player's in-game wishlist. #### `GET /wishlist`: Get player wishlist - Anchor: `#operation-getplayerwishlist` - Operation ID: `getPlayerWishlist` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns the items on a player's in-game wishlist. **Region:** optional. Defaults to `ind` when omitted. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `region` | query | string | no | Region of the player's account. Recommended on every request. - `sg`: Singapore region (SG, ID, ME, VN, TH, CIS, EU, TW, MY, PK, BD) - `ind`: India region (India only) - `br`: Brazil region (BR, US, NA, LATAM) When omitted, `/stats` and `/wishlist` default to `ind` and `/craftland` defaults to `sg`. `/info` forwards the value to the data provider as-is. Allowed: `sg`, `ind`, `br`. Example: `"ind"` | | `uid` | query | string | yes | The player's unique User ID (5 to 15 digits). Pattern: `^\d{5,15}$`. Example: `"665951869"` | **Responses** - `200`: Wishlist retrieved. (`application/json`) Type: `WishlistResponse` - `wishlist_items` (object[]): Wishlist entries. ```json { "wishlist_items": [ {} ] } ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `404`: Player not found or wishlist is empty. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/wishlist?region=ind&uid=665951869" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Guild Information Guild (clan) details. #### `GET /guild`: Get guild information - Anchor: `#operation-getguildinfo` - Operation ID: `getGuildInfo` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns guild (clan) information. Query parameters other than the API key are forwarded to the data provider. **Region:** optional. Defaults to `br` when omitted. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `region` | query | string | no | Region code of the guild. Allowed: `sg`, `ind`, `br`. Default: `"br"`. Example: `"br"` | **Responses** - `200`: Guild information retrieved. (`application/json`) Type: `object`. Guild details as returned by the data provider. ```json {} ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `502`: The data provider failed or returned a non-JSON response (`SYS_002`). Includes `upstreamStatus` when available. Safe to retry. `Retry-After` is 5 seconds on connection failures. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `504`: The data provider did not respond within 8 seconds (`SYS_003`). Retry after the `Retry-After` interval (5 seconds). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/guild?region=br" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Craftland Maps Custom Craftland maps and user-generated content. #### `GET /craftland`: Get Craftland map information - Anchor: `#operation-getcraftlandmapinfo` - Operation ID: `getCraftlandMapInfo` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns detailed information about a specific Craftland custom map. **Region:** optional. Defaults to `sg` when omitted. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `region` | query | string | no | Region of the player's account. Recommended on every request. - `sg`: Singapore region (SG, ID, ME, VN, TH, CIS, EU, TW, MY, PK, BD) - `ind`: India region (India only) - `br`: Brazil region (BR, US, NA, LATAM) When omitted, `/stats` and `/wishlist` default to `ind` and `/craftland` defaults to `sg`. `/info` forwards the value to the data provider as-is. Allowed: `sg`, `ind`, `br`. Example: `"ind"` | | `code` | query | string | yes | The Craftland map code. Example: `"FREEFIRE625B83664022B40F67CBFBFF9CC3C1247490"` | **Responses** - `200`: Map information retrieved. (`application/json`) Type: `CraftlandMapResponse` - `map_info` (object): Details of the requested map. ```json { "map_info": {} } ``` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `404`: Map not found. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/craftland?region=sg&code=FREEFIRE625B83664022B40F67CBFBFF9CC3C1247490" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" ``` ### Game Assets In-game images, icons and other visual assets. #### `GET /image`: Get game asset image - Anchor: `#operation-getgameimages` - Operation ID: `getGameImages` - Authentication: `ApiKeyAuth` (API key in header: x-api-key) or `ApiKeyQueryAuth` (API key in query: key) Returns an in-game image or icon from the Free Fire asset database, such as: - Character avatars and skins - Weapon skins and icons - Item and equipment icons - Badges and banners - Pet images **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `itemID` | query | string | yes | The item ID to retrieve the image for. Pattern: `^\d+$`. Example: `"908028011"` | **Responses** - `200`: Image retrieved. (`image/png`) Type: `string(binary)` - `400`: Bad request. A required parameter is missing or invalid (for example `PARAM_001`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `401`: Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with `ffc_` and are at least 30 characters. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `403`: Forbidden. Two causes: (1) an edge firewall block, where the error `code` starts with `FW_` (for example `FW_001` for a missing or short User-Agent, `FW_002` for a blocked User-Agent pattern). Set a valid custom `User-Agent` header. (2) The API key is inactive (`AUTH_003`) or expired (`AUTH_004`). The region is never the cause. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `404`: Image not found. (`application/json`). Body: `ErrorResponse` (see "Error response schemas") - `429`: Too many requests. The `code` is `RATE_001` (per-minute, per-hour or per-IP limit; check `window` and `type`), `QUOTA_001` (monthly quota exhausted; see `used`, `limit`, `requestCost` and `resetDate`), or `FW_004` (edge firewall limit; honor `Retry-After`). (`application/json`). Body: `ErrorResponse` (see "Error response schemas") **Example request** ```bash curl "https://developers.freefirecommunity.com/api/v1/image?itemID=908028011" \ -H "x-api-key: your_api_key_here" \ -H "User-Agent: MyApp/1.0 (+https://example.com/my-app)" \ --output item.png ``` ## Error response schemas ### ErrorResponse Type: `ErrorResponse` - `success` (boolean): Example: `false` - `error` (string): Short error name. - `message` (string): Human-readable explanation. - `code` (string): Machine-readable error code: `AUTH_001` (missing key), `AUTH_002` (invalid key), `AUTH_003` (inactive key), `AUTH_004` (expired key), `RATE_001` (rate limit), `QUOTA_001` (monthly quota), `PARAM_001` (missing parameter), `RES_001` (not found), `SYS_001` (internal error), `SYS_002` (service unavailable), `SYS_003` (upstream timeout), or `FW_001` to `FW_004` (edge firewall). Example: `"AUTH_001"` - `requestId` (string): Request identifier, included on 5xx errors. Quote it when contacting support. - `retryAfter` (integer): Seconds to wait before retrying, when applicable. - `documentation` (string(uri)): Link to documentation for this error. - `timestamp` (string(date-time)) ## More information - [Get an API key and read the full documentation](https://developers.freefirecommunity.com/)