openapi: 3.0.3
info:
  title: Free Fire Community API
  version: '2.0'
  description: |
    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)
  contact:
    name: Free Fire Community API Support
    url: https://developers.freefirecommunity.com/en/contact
    email: developers@freefirecommunity.com
  license:
    name: API License Agreement
    url: https://developers.freefirecommunity.com/en/terms
  termsOfService: https://developers.freefirecommunity.com/en/terms
  # x-logo:
  #   url: https://your-host/logo.png   # square or wide PNG/SVG, shown in the header and overview
  #   altText: Free Fire Community API
  x-og-image:
    url: https://developers.freefirecommunity.com/og-image.png
    alt: Free Fire Community API
  x-api-id: free-fire-community-api
  x-keywords:
    - free fire api
    - free fire stats
    - free fire player data
    - garena free fire api
    - free fire statistics
    - free fire developer api
    - free fire rest api
    - free fire player stats
    - free fire game data

servers:
  - url: https://developers.freefirecommunity.com/api/v1
    description: Production API server (version 1)

tags:
  - name: Player Information
    description: Player profile data, rankings, clan and account information.
  - name: Player Statistics
    description: Career gameplay statistics for Solo, Duo and Squad modes.
  - name: Player Ban Check
    description: Check whether a player account is banned or has an active ban period.
  - name: Player Wishlist
    description: Items on a player's in-game wishlist.
  - name: Guild Information
    description: Guild (clan) details.
  - name: Craftland Maps
    description: Custom Craftland maps and user-generated content.
  - name: Game Assets
    description: In-game images, icons and other visual assets.

paths:
  /info:
    get:
      tags:
        - Player Information
      summary: Get player information
      description: |
        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.
      operationId: getPlayerInfo
      parameters:
        - $ref: '#/components/parameters/RegionParam'
        - $ref: '#/components/parameters/UIDParam'
      responses:
        '200':
          description: Player information retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerInfoResponse'
              example:
                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':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/info?region=ind&uid=665951869',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/info',
                params={'region': 'ind', 'uid': '665951869'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /stats:
    get:
      tags:
        - Player Statistics
      summary: Get player statistics
      description: |
        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.
      operationId: getPlayerStats
      parameters:
        - $ref: '#/components/parameters/RegionParam'
        - $ref: '#/components/parameters/UIDParam'
      responses:
        '200':
          description: Player statistics retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerStatsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/stats?region=ind&uid=665951869',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/stats',
                params={'region': 'ind', 'uid': '665951869'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /bancheck:
    get:
      tags:
        - Player Ban Check
      summary: Check player ban status
      description: |
        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.
      operationId: checkPlayerBanStatus
      parameters:
        - $ref: '#/components/parameters/UIDParam'
        - name: lang
          in: query
          required: false
          description: Language for the response.
          schema:
            type: string
            enum: [en, ar, es, id, pt, ru, vi]
            default: en
          example: en
      responses:
        '200':
          description: Ban check completed.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BanCheckResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/bancheck?uid=665951869&lang=en',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/bancheck',
                params={'uid': '665951869', 'lang': 'en'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /wishlist:
    get:
      tags:
        - Player Wishlist
      summary: Get player wishlist
      description: |
        Returns the items on a player's in-game wishlist.

        **Region:** optional. Defaults to `ind` when omitted.
      operationId: getPlayerWishlist
      parameters:
        - $ref: '#/components/parameters/RegionParam'
        - $ref: '#/components/parameters/UIDParam'
      responses:
        '200':
          description: Wishlist retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Player not found or wishlist is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/wishlist?region=ind&uid=665951869',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/wishlist',
                params={'region': 'ind', 'uid': '665951869'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /guild:
    get:
      tags:
        - Guild Information
      summary: Get guild information
      description: |
        Returns guild (clan) information. Query parameters other than the API key are
        forwarded to the data provider.

        **Region:** optional. Defaults to `br` when omitted.
      operationId: getGuildInfo
      parameters:
        - name: region
          in: query
          required: false
          description: Region code of the guild.
          schema:
            type: string
            enum: [sg, ind, br]
            default: br
          example: br
      responses:
        '200':
          description: Guild information retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                type: object
                description: Guild details as returned by the data provider.
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/guild?region=br',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/guild',
                params={'region': 'br'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /craftland:
    get:
      tags:
        - Craftland Maps
      summary: Get Craftland map information
      description: |
        Returns detailed information about a specific Craftland custom map.

        **Region:** optional. Defaults to `sg` when omitted.
      operationId: getCraftlandMapInfo
      parameters:
        - $ref: '#/components/parameters/RegionParam'
        - name: code
          in: query
          required: true
          description: The Craftland map code.
          schema:
            type: string
          example: 'FREEFIRE625B83664022B40F67CBFBFF9CC3C1247490'
      responses:
        '200':
          description: Map information retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CraftlandMapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Map not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-code-samples:
        - lang: cURL
          source: |
            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)"
        - lang: JavaScript
          source: |
            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/craftland?region=sg&code=FREEFIRE625B83664022B40F67CBFBFF9CC3C1247490',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            const data = await response.json();
            console.log(data);
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/craftland',
                params={'region': 'sg', 'code': 'FREEFIRE625B83664022B40F67CBFBFF9CC3C1247490'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            print(response.json())

  /image:
    get:
      tags:
        - Game Assets
      summary: Get game asset image
      description: |
        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
      operationId: getGameImages
      parameters:
        - name: itemID
          in: query
          required: true
          description: The item ID to retrieve the image for.
          schema:
            type: string
            pattern: '^\d+$'
          example: '908028011'
      responses:
        '200':
          description: Image retrieved.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Image not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-code-samples:
        - lang: cURL
          source: |
            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
        - lang: JavaScript
          source: |
            import { writeFile } from 'node:fs/promises';

            const response = await fetch(
              'https://developers.freefirecommunity.com/api/v1/image?itemID=908028011',
              {
                headers: {
                  'x-api-key': 'your_api_key_here',
                  'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
              }
            );
            await writeFile('item.png', Buffer.from(await response.arrayBuffer()));
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://developers.freefirecommunity.com/api/v1/image',
                params={'itemID': '908028011'},
                headers={
                    'x-api-key': 'your_api_key_here',
                    'User-Agent': 'MyApp/1.0 (+https://example.com/my-app)',
                },
            )
            with open('item.png', 'wb') as file:
                file.write(response.content)

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        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:
      type: apiKey
      in: query
      name: key
      description: |
        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.

  parameters:
    RegionParam:
      name: region
      in: query
      required: false
      description: |
        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.
      schema:
        type: string
        enum: [sg, ind, br]
      example: ind

    UIDParam:
      name: uid
      in: query
      required: true
      description: The player's unique User ID (5 to 15 digits).
      schema:
        type: string
        pattern: '^\d{5,15}$'
      example: '665951869'

  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed in the current per-minute window.
      schema:
        type: integer
      example: 60

    X-RateLimit-Remaining:
      description: Requests remaining in the current per-minute window.
      schema:
        type: integer
      example: 45

    X-RateLimit-Reset:
      description: Time when the per-minute window resets (Unix timestamp).
      schema:
        type: integer
      example: 1735689600

    X-Quota-Cost:
      description: Monthly quota units used by this request (1 for most endpoints, 2 for `/stats`).
      schema:
        type: integer
      example: 1

    X-Cache:
      description: Whether the response was served from the server-side cache.
      schema:
        type: string
        enum: [HIT, MISS]
      example: MISS

  schemas:
    PlayerInfoResponse:
      type: object
      description: Comprehensive player information.
      required:
        - basicInfo
      properties:
        basicInfo:
          $ref: '#/components/schemas/PlayerBasicInfo'
        captainBasicInfo:
          $ref: '#/components/schemas/PlayerBasicInfo'
        clanBasicInfo:
          $ref: '#/components/schemas/ClanBasicInfo'
        petInfo:
          $ref: '#/components/schemas/PetInfo'
        creditScoreInfo:
          $ref: '#/components/schemas/CreditScoreInfo'
        diamondCostRes:
          $ref: '#/components/schemas/DiamondCostResponse'
        profileInfo:
          $ref: '#/components/schemas/ProfileInfo'
        socialInfo:
          $ref: '#/components/schemas/SocialInfo'
      additionalProperties: true

    PlayerBasicInfo:
      type: object
      description: Core account and ranking information.
      properties:
        accountId:
          type: string
          description: Player account ID.
        nickname:
          type: string
          description: Player display name.
        level:
          type: integer
          description: Account level.
        rank:
          type: integer
          description: Current Battle Royale rank.
        maxRank:
          type: integer
          description: Highest Battle Royale rank reached.
        csRank:
          type: integer
          description: Current Clash Squad rank.
        csMaxRank:
          type: integer
          description: Highest Clash Squad rank reached.
        rankingPoints:
          type: integer
          description: Current ranking points.
        region:
          type: string
          description: Account region.
        seasonId:
          type: integer
          description: Current season ID.
        liked:
          type: integer
          description: Number of likes the profile has received.
        title:
          type: string
          description: Equipped title.
        badgeId:
          type: string
          description: Equipped badge ID.
        bannerId:
          type: string
          description: Equipped banner ID.
      additionalProperties: true

    ClanBasicInfo:
      type: object
      description: Clan (guild) the player belongs to.
      properties:
        clanId:
          type: string
          description: Clan ID.
        clanName:
          type: string
          description: Clan name.
        captainId:
          type: string
          description: Account ID of the clan captain.
        clanLevel:
          type: integer
          description: Clan level.
        memberNum:
          type: integer
          description: Current number of members.
        capacity:
          type: integer
          description: Maximum number of members.
      additionalProperties: true

    PetInfo:
      type: object
      description: The player's pet.
      properties:
        id:
          type: string
          description: Pet ID.
        skinId:
          type: string
          description: Equipped pet skin ID.
        selectedSkillId:
          type: string
          description: Selected pet skill ID.
        level:
          type: integer
          description: Pet level.
        exp:
          type: integer
          description: Pet experience points.
        isSelected:
          type: boolean
          description: Whether this pet is currently equipped.
      additionalProperties: true

    CreditScoreInfo:
      type: object
      description: Account credit score and reward state.
      properties:
        creditScore:
          type: integer
          description: Current credit score.
        rewardStartAt:
          type: string
          description: Reward period start.
        rewardEndAt:
          type: string
          description: Reward period end.
        rewardState:
          type: integer
          description: Reward state code.
        rewardType:
          type: integer
          description: Reward type code.
      additionalProperties: true

    DiamondCostResponse:
      type: object
      description: Diamond spending summary.
      properties:
        diamondCost:
          type: integer
          description: Diamonds spent.

    ProfileInfo:
      type: object
      description: Equipped avatar, clothes and skills.
      properties:
        avatarId:
          type: string
          description: Equipped avatar ID.
        clothes:
          type: array
          description: IDs of equipped clothing items.
          items:
            type: string
        equipedSkills:
          type: array
          description: Equipped character skills.
          items:
            type: object
            additionalProperties: true
        isSelected:
          type: boolean
          description: Whether this profile setup is currently selected.
        isSelectedAwaken:
          type: boolean
          description: Whether the awakened variant is selected.
      additionalProperties: true

    SocialInfo:
      type: object
      description: Social profile details.
      properties:
        accountId:
          type: string
          description: Player account ID.
        signature:
          type: string
          description: Profile signature text.
      additionalProperties: true

    PlayerStatsResponse:
      type: object
      description: Career statistics grouped by Battle Royale mode.
      properties:
        brCareer_solo:
          type: object
          description: Solo mode career statistics.
          additionalProperties: true
        brCareer_duo:
          type: object
          description: Duo mode career statistics.
          additionalProperties: true
        brCareer_squad:
          type: object
          description: Squad mode career statistics.
          additionalProperties: true

    CraftlandMapResponse:
      type: object
      description: Craftland custom map information.
      properties:
        map_info:
          type: object
          description: Details of the requested map.
          additionalProperties: true

    WishlistResponse:
      type: object
      description: Items on the player's wishlist.
      properties:
        wishlist_items:
          type: array
          description: Wishlist entries.
          items:
            type: object
            additionalProperties: true

    BanCheckResponse:
      type: object
      description: Player ban status.
      properties:
        status:
          type: string
          description: Status of the ban check request.
        data:
          type: object
          properties:
            is_banned:
              type: integer
              enum: [0, 1]
              description: "`1` if the account is banned, otherwise `0`."
            period:
              type: integer
              description: Ban period reported by the data provider.

    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Short error name.
        message:
          type: string
          description: Human-readable explanation.
        code:
          type: string
          description: |
            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:
          type: string
          description: Request identifier, included on 5xx errors. Quote it when contacting support.
        retryAfter:
          type: integer
          description: Seconds to wait before retrying, when applicable.
        documentation:
          type: string
          format: uri
          description: Link to documentation for this error.
        timestamp:
          type: string
          format: date-time
      additionalProperties: true

  responses:
    BadRequest:
      description: Bad request. A required parameter is missing or invalid (for example `PARAM_001`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Unauthorized:
      description: >-
        Unauthorized. The key is missing (`AUTH_001`) or invalid (`AUTH_002`). Keys start with
        `ffc_` and are at least 30 characters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Forbidden:
      description: >-
        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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    TooManyRequests:
      description: >-
        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`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    BadGateway:
      description: >-
        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.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    GatewayTimeout:
      description: >-
        The data provider did not respond within 8 seconds (`SYS_003`). Retry after the
        `Retry-After` interval (5 seconds).
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    ServiceUnavailable:
      description: >-
        Service temporarily unavailable (`SYS_002`), for example when the backend could not
        initialize. Retry after `Retry-After` (30 seconds).
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    InternalServerError:
      description: Internal server error (`SYS_001`). Include the `requestId` when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

security:
  - ApiKeyAuth: []
  - ApiKeyQueryAuth: []

externalDocs:
  description: Get an API key and read the full documentation
  url: https://developers.freefirecommunity.com/
