API Documentation

KAL’s public API is still in beta and unstable, and parts of it may change substantially. If you have ideas, suggestions, requests, questions, or run into an issue, send Kalends [2032147] a chat on Torn or, preferably, join the KAL Discord so you will also be notified when API behavior changes.

Every authenticated endpoint accepts either Authorization: ApiKey YOUR_TORN_API_KEY or ?key=YOUR_TORN_API_KEY. Both authentication methods are supported.

The main API read limit is currently 100 calls per KAL account per minute. Rate limiting will probably move to endpoint-specific, IP-based limits soonish.

The UI/format for these API docs is based on Glasnost [1844049]’s API docs.

Get Player Loadout Endpoint

Returns the latest saved KAL loadout for a Torn player. Use cursor to retrieve older distinct loadouts.

Endpoint

GET /user/{id}/loadout

Required Parameters

Optional Parameters

Example Request

curl "https://api.kalends.dev/user/2032147/loadout" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "user_id": 2032147,
  "name": "Kalends",
  "observed_at": 1786331700,
  "equipment": [
    {
      "id": 398,
      "item_ref": "kAbCdEfGhIjK",
      "name": "SIG 552",
      "type": "Weapon",
      "sub_type": "Rifle",
      "stats": {
        "damage": 77.19,
        "accuracy": 56.26,
        "armor": null,
        "quality": 41.72
      },
      "bonuses": [
        {
          "id": 81,
          "title": "Warlord",
          "description": "24% increased respect upon final hit",
          "value": 24,
          "rarity": "red"
        }
      ],
      "rarity": "orange",
      "slot": 1,
      "slot_name": "primary",
      "ammo": {
        "id": 5,
        "category_id": 4,
        "type": "Tracer"
      },
      "mods": [
        {
          "id": 5,
          "name": "1mW Laser",
          "description": "+2% critical hit rate"
        }
      ],
      "effect": null,
      "blocked_effects": []
    }
  ],
  "pagination": {
    "next_cursor": "CURSOR_VALUE"
  }
}

Response Fields

Error Codes Reference

Notes

• The endpoint uses stored KAL data and does not contact Torn.
• Return pagination.next_cursor unchanged with the same player ID to retrieve the next older distinct loadout.
• Invalid or unavailable cursors use the same 404 response as unavailable loadout history.
• item_ref is KAL’s public exact-item identifier. It is not the raw Torn owned-item UID.
• Unknown item, bonus, mod, or slot descriptive metadata is returned as null.

Get Human-Readable Player Loadout Endpoint

Returns the same selected loadout as plain text.

Endpoint

GET /user/{id}/loadout/text

Required Parameters

Optional Parameters

Example Request

curl "https://api.kalends.dev/user/2032147/loadout/text" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

=== KAL Loadout Reveal (Kalends [2032147]) ===
Observed: 2026-08-10T03:15:00+00:00

Primary: SIG 552
damage: 77.19, accuracy: 56.26, quality: 41.72
Bonuses:
- Warlord: 24% increased respect upon final hit

Error Codes Reference

Same authentication, pagination, validation, not-found, and rate-limit errors as GET /user/{id}/loadout.

Notes

• Content type is text/plain; charset=utf-8.
• Exact text formatting may change; use the JSON endpoint for machine-readable integrations.

Get Faction Loadouts Endpoint

Returns KAL’s stored faction roster with each member’s latest visible saved loadout.

Endpoint

GET /faction/{id}/loadouts

Required Parameters

Example Request

curl "https://api.kalends.dev/faction/7835/loadouts" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "faction_id": 7835,
  "name": "Example faction",
  "tag": "KAL",
  "members_observed_at": 1786331700,
  "members": [
    {
      "user_id": 2032147,
      "name": "Kalends",
      "loadout": {
        "observed_at": 1786331700,
        "equipment": []
      }
    },
    {
      "user_id": 1234567,
      "name": "Example player",
      "loadout": null
    }
  ]
}

Response Fields

Error Codes Reference

Notes

• The endpoint uses KAL’s stored roster and does not perform a live Torn faction refresh.
• loadout: null means the member is known but KAL has no visible saved loadout to return.

Get Player Combat Specials Endpoint

Returns combat-related company/job specials from KAL’s stored employment data.

Endpoint

GET /user/{id}/combat-specials

Required Parameters

Example Request

curl "https://api.kalends.dev/user/2032147/combat-specials" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "user_id": 2032147,
  "name": "Kalends",
  "updated_at": 1786331700,
  "company_name": "Example company",
  "company_type_id": 28,
  "company_rating": 9,
  "specials": [
    {
      "name": "Combat training",
      "effect": "Example combat effect",
      "job_point_cost": 10,
      "required_star": 7
    }
  ]
}

Response Fields

Error Codes Reference

Notes

• The endpoint uses stored KAL data and does not contact Torn.
• updated_at is the employment-data timestamp, not the player’s loadout timestamp.

Search Ranked Items Endpoint

Searches exact ranked weapon and armor instances stored by KAL.

Endpoint

GET /ranked-items

Required Parameters

Optional Parameters

Example Request

curl --get "https://api.kalends.dev/ranked-items" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY" \
  --data-urlencode "category=weapons" \
  --data-urlencode "source=loadout" \
  --data-urlencode "bonus1=81" \
  --data-urlencode "sort=bonus1" \
  --data-urlencode "direction=desc" \
  --data-urlencode "limit=25"

Example Response

{
  "items": [
    {
      "item_ref": "kAbCdEfGhIjK",
      "id": 398,
      "name": "SIG 552",
      "type": "Weapon",
      "sub_type": "Rifle",
      "stats": {
        "damage": 77.19,
        "accuracy": 56.26,
        "armor": null,
        "quality": 41.72
      },
      "bonuses": [
        {
          "id": 81,
          "title": "Warlord",
          "description": "24% increased respect upon final hit",
          "value": 24,
          "rarity": "red"
        }
      ],
      "rarity": "orange",
      "slot": 1,
      "slot_name": "primary",
      "sources": [
        {
          "type": "loadout",
          "latest_appearance": {
            "user_id": 2032147,
            "name": "Kalends",
            "slot": 1,
            "slot_name": "primary",
            "observed_at": 1786331700
          }
        },
        {
          "type": "auction",
          "latest_sale": {
            "listing_id": 9000000001,
            "ended_at": 1786331800,
            "price": 123456789,
            "bids": 7,
            "seller_id": 123456,
            "buyer_id": 789012
          }
        }
      ]
    }
  ],
  "total": null,
  "pagination": {
    "next_cursor": "CATALOG_CURSOR"
  }
}

Response Fields

Error Codes Reference

Notes

• All supplied filters are ANDed together.
• Category-incompatible filters return 422 instead of being ignored.
• Unknown item or bonus descriptive metadata is returned as null.
• bonus1 and bonus2 are query labels, not physical bonus positions.
• source requires that visible evidence source. Source-specific filters can independently require another source.
• Return pagination.next_cursor unchanged with the same filters, sort, direction, and visibility context.
• Syntactically valid filters with no matches return HTTP 200 with items: [].
• The endpoint uses stored KAL data and does not contact Torn.

Get Exact Item Endpoint

Resolves one exact item by KAL item_ref or a positive raw Torn owned-item UID.

Endpoint

GET /items/{item}

Required Parameters

Example Request

curl "https://api.kalends.dev/items/kAbCdEfGhIjK" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "item_ref": "kAbCdEfGhIjK",
  "id": 398,
  "name": "SIG 552",
  "type": "Weapon",
  "sub_type": "Rifle",
  "stats": {
    "damage": 77.19,
    "accuracy": 56.26,
    "armor": null,
    "quality": 41.72
  },
  "bonuses": [
    {
      "id": 81,
      "title": "Warlord",
      "description": "24% increased respect upon final hit",
      "value": 24,
      "rarity": "red"
    }
  ],
  "rarity": "orange",
  "slot": 1,
  "slot_name": "primary",
  "sources": [
    {
      "type": "loadout",
      "latest_appearance": {
        "user_id": 2032147,
        "name": "Kalends",
        "slot": 1,
        "slot_name": "primary",
        "observed_at": 1786331700
      }
    }
  ]
}

Response Fields

Same item shape as entries returned by GET /ranked-items.

Error Codes Reference

Notes

• Responses always use item_ref as the canonical public exact-item identifier.
• KAL item refs begin with k; positive numeric identifiers are treated as caller-supplied Torn owned-item UIDs.
• A raw Torn owned-item UID is lookup-only and is not echoed as the public identity.
• Unknown and not-visible item identifiers share the same 404 response.

Get Exact Item History Endpoint

Returns visible loadout appearances and completed auction sales for one exact item, newest first.

Endpoint

GET /items/{item}/history

Required Parameters

Optional Parameters

Example Request

curl "https://api.kalends.dev/items/kAbCdEfGhIjK/history?limit=25" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "item_ref": "kAbCdEfGhIjK",
  "history": [
    {
      "type": "auction",
      "listing_id": 9000000001,
      "ended_at": 1786331800,
      "price": 123456789,
      "bids": 7,
      "seller_id": 123456,
      "buyer_id": 789012
    },
    {
      "type": "loadout",
      "user_id": 2032147,
      "name": "Kalends",
      "slot": 1,
      "slot_name": "primary",
      "observed_at": 1786331700,
      "loadout_cursor": "LOADOUT_CURSOR"
    }
  ],
  "pagination": {
    "next_cursor": "HISTORY_CURSOR"
  }
}

Response Fields

Error Codes Reference

Notes

• pagination.next_cursor paginates the item-history stream.
• A loadout event’s loadout_cursor is different: pass it to GET /user/{user_id}/loadout?cursor=... to retrieve that distinct loadout.
• An otherwise visible item with no matching events returns HTTP 200 with history: [].
• The endpoint uses stored KAL data and does not contact Torn.

Check API Key Status Endpoint

Endpoint

GET /check-key

Required Parameters

Example Request

curl "https://api.kalends.dev/check-key" \
  -H "Authorization: ApiKey YOUR_TORN_API_KEY"

Example Response

{
  "is_registered": true
}

Response Fields

Error Codes Reference

Notes

• This endpoint checks KAL’s stored state only. It does not contact Torn.
• This endpoint does not register an API key.
• This endpoint does not consume the main API read budget; repeated unrecognized keys are subject to separate abuse protection.
• A well-formed key that is unknown, revoked, erased, or never registered returns HTTP 200 with is_registered: false.