API Reference

Pull your gearcheck data, test builds programmatically, or export everything as CSV. The API is available to Subscriber and Premium tiers.

On this page

Authentication
Builds
Analytics
Data Exports
Rate Limits
Errors

Authentication

The API uses your Discord account for authentication. Sign in through the web dashboard to get a session token, then include it in your requests.

Include this header on every request

Authorization: Bearer <your-token>

To get a token, sign in at the web dashboard. Your browser stores the token automatically. If you need a token for scripts or external tools, you can grab it from your browser's developer console (localStorage, key: token).

Scope: You can only access data for servers where you have the Manage Server permission and the bot is present. Tokens expire after 24 hours.

Builds

Read your build specs and test them against sample text.

GET/api/guilds/{guild_id}/buildsSubscriber+

List all builds for a server, grouped by activity.

Response

{
  "builds": [
    {
      "key": "rapier_evader_v1",
      "display_name": "Rapier Evader",
      "activity": "wurmmy",
      "category_count": 5,
      "build_url": "",
      "thresholds": { "verified": 85, "tentative": 80, "borderline": 75 }
    }
  ],
  "total": 32
}

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/builds

GET/api/guilds/{guild_id}/builds/{build_key}Subscriber+

Get full build details including all categories and items.

Response

{
  "key": "rapier_evader_v1",
  "display_name": "Rapier Evader",
  "activity": "wurmmy",
  "thresholds": { "verified": 85, "tentative": 80, "borderline": 75 },
  "categories": [
    {
      "key": "weapons",
      "name": "Weapons",
      "icon": "",
      "weight": 1.0,
      "items": [
        {
          "name": "Rapier",
          "aliases": ["rapier"],
          "exclude": [],
          "target": 1
        }
      ]
    }
  ]
}

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/builds/rapier_evader_v1

POST/api/guilds/{guild_id}/builds/{build_key}/testSubscriber+

Test a build against sample text. Useful for validating aliases or debugging OCR output. Returns a full score breakdown without needing to upload screenshots.

Request Body

{
  "text": "rapier leeching flurry refreshing move"
}

Response

{
  "score": 72.5,
  "status": "unverified",
  "categories": [
    {
      "name": "Weapons",
      "items": [
        { "name": "Rapier", "status": "match", "count": 1 }
      ]
    },
    {
      "name": "Perks",
      "items": [
        { "name": "Leeching Flurry", "status": "match", "count": 1 },
        { "name": "Refreshing", "status": "miss", "count": 0 }
      ]
    }
  ]
}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "rapier leeching flurry refreshing move"}' \
  https://api.gearcheck.gg/api/guilds/987654321/builds/rapier_evader_v1/test

Analytics

Server-level gearcheck stats.

GET/api/guilds/{guild_id}/analyticsSubscriber+

Get gearcheck analytics for your server. Total checks, pass count, and verification rate.

Response

{
  "total_checks": 247,
  "total_verified": 189,
  "verification_rate": 76.5,
  "tier": "subscriber"
}

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/analytics

Data Exports

Download your data as JSON or CSV. Great for spreadsheets, external dashboards, or just keeping a backup. Add ?format=csv for CSV or ?format=json for JSON (default).

GET/api/guilds/{guild_id}/export/builds?format=csvSubscriber+

Export all builds as a flat CSV. One row per item, with columns for build name, activity, category, item name, aliases, target count, and weight.

Response

build_name,activity,category,item_name,aliases,target,weight
Rapier Evader,wurmmy,Weapons,Rapier,"rapier",1,1.0
Rapier Evader,wurmmy,Perks,Leeching Flurry,"leeching flurry;leeching",1,1.0
...

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/export/builds?format=csv \
  -o builds.csv

GET/api/guilds/{guild_id}/export/analytics?format=csvSubscriber+

Export analytics data as CSV.

Response

total_checks,total_verified,verification_rate
247,189,76.5

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/export/analytics?format=csv \
  -o analytics.csv

GET/api/guilds/{guild_id}/export/checks?format=csvSubscriber+

Export all completed gearchecks. One row per check, with thread ID, build name, score, status, and completion time.

Response

thread_id,build_name,score,status,completion_time
1486117328084140143,Rapier Evader,87.5,verified,2026-03-28T14:30:00
1486122348087087255,Tank v3,72.0,unverified,2026-03-28T15:45:00
...

Example

curl -H "Authorization: Bearer <token>" \
  https://api.gearcheck.gg/api/guilds/987654321/export/checks?format=csv \
  -o checks.csv

Rate Limits

The API allows 60 requests per minuteper authenticated user. If you exceed this, you'll get a 429 response. Wait and retry.

HTTP/1.1 429 Too Many Requests
{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}

Errors

All errors return a JSON body with a detail field explaining what went wrong.

Code	Meaning	When
401	Unauthorized	Missing or expired token
402	Payment Required	Endpoint requires a higher tier
403	Forbidden	You don't have admin access to this server
404	Not Found	Build, category, or item doesn't exist
429	Too Many Requests	Rate limit exceeded