Developer Reference

API Reference

Pull guild-owned data, inspect builds, test specs, and export verification history. These routes document the dashboard-backed resources and supported export workflows.

Access model: GearCheck uses Discord sign-in and a dashboard session cookie for web API calls. The examples below show the major resource families and current route shape; use dashboard exports when you need data outside GearCheck.

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, then the browser sends the session cookie with dashboard requests. You can only access guilds where your Discord user has the required GearCheck permission.

Dashboard requests

Cookie: gearcheck_session=<dashboard-session-cookie>

For normal usage, you do not need to copy this cookie or use developer tools. Use the dashboard exports for CSV and JSON downloads. Dedicated external API keys are not self-service yet.

Scope: Access is permission-gated per guild. Managers, moderators, assistants, and analytics viewers may see different data depending on the permission set configured for the server.

Builds

Read your build specs and test them against sample text.

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

List all builds for a pack, 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 "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/packs/main/builds

GET/api/guilds/{guild_id}/packs/{pack_key}/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 "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/packs/main/builds/rapier_evader_v1

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

Test an OCR-style build against sample text. Useful for validating aliases or investigating OCR output. Structured evidence import/testing is handled by the dashboard build editor.

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 "Cookie: gearcheck_session=<session>" \
  -H "Content-Type: application/json" \
  -d '{"text": "rapier leeching flurry refreshing move"}' \
  https://api.gearcheck.gg/api/guilds/987654321/packs/main/builds/rapier_evader_v1/test

Analytics

Server-level gearcheck stats.

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

Get GearCheck analytics for your server, including verification trends, evidence source coverage, pack summaries, and top builds.

Response

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

Example

curl -H "Cookie: gearcheck_session=<session>" \
  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}/packs/{pack_key}/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 "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/packs/main/export/builds?format=csv \
  -o builds.csv

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

Export analytics data as CSV.

Response

total_checks,total_verified,verification_rate
247,189,76.5

Example

curl -H "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/packs/main/export/analytics?format=csv \
  -o analytics.csv

GET/api/guilds/{guild_id}/verifications/export.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 "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/verifications/export.csv \
  -o checks.csv

GET/api/guilds/{guild_id}/data-inventory/export.csvSubscriber+

Export the guild data inventory, including data families, counts, export paths, and known gaps. Useful for staff audits and ownership reviews.

Response

family,key,label,value
verification_sessions,total,Verification sessions,247
content,builds,Builds,32
...

Example

curl -H "Cookie: gearcheck_session=<session>" \
  https://api.gearcheck.gg/api/guilds/987654321/data-inventory/export.csv \
  -o data-inventory.csv

Rate Limits

The API allows 60 requests per minute per 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