{"openapi":"3.1.0","info":{"title":"KAL API (Beta)","description":"This 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]](https://www.torn.com/profiles.php?XID=2032147) a chat on Torn or, preferably, join the [KAL Discord](https://discord.gg/aKHq5Yfx8n) so you will also be notified when API behavior changes.\n\nThe 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.\n\nAuthenticate with either `Authorization: ApiKey YOUR_TORN_API_KEY` or `?key=YOUR_TORN_API_KEY`. Both authentication methods are supported.","version":"0.1.0-beta"},"paths":{"/check-key":{"get":{"tags":["Authentication"],"summary":"Check API key registration","description":"Checks whether a Torn API key is registered with KAL. This does not register the key or call Torn. Unknown keys return is_registered=false.","operationId":"checkPublicApiKey","parameters":[{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckKeyResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required, invalid, or disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4 or 6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: authentication attempt rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/user/{id}/loadout":{"get":{"tags":["Loadouts"],"summary":"Get a player's latest or previous loadout","description":"Returns the latest recorded loadout for a player. Supply cursor to get the next older distinct loadout. Pass pagination.next_cursor back unchanged for the same player. item_ref identifies an exact item in KAL. Timestamps are Unix seconds.","operationId":"getUserLoadout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","maximum":9223372036854775807,"exclusiveMinimum":0,"description":"Torn player ID.","title":"Id"},"description":"Torn player ID."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"pagination.next_cursor returned by an earlier response.","title":"Cursor"},"description":"pagination.next_cursor returned by an earlier response."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loadout"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: invalid player ID or query value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: loadout or cursor not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/user/{id}/loadout/text":{"get":{"tags":["Loadouts"],"summary":"Get a human-readable loadout","description":"Returns the same loadout as the JSON endpoint as text/plain. Formatting may change; use the JSON endpoint for integrations.","operationId":"getUserLoadoutText","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","maximum":9223372036854775807,"exclusiveMinimum":0,"description":"Torn player ID.","title":"Id"},"description":"Torn player ID."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"pagination.next_cursor returned by an earlier JSON response.","title":"Cursor"},"description":"pagination.next_cursor returned by an earlier JSON response."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: invalid player ID or query value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: loadout or cursor not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/user/{id}/combat-specials":{"get":{"tags":["Users"],"summary":"Get a player's combat job specials","description":"Returns combat-related company specials from KAL's latest employment data. updated_at is the employment-data timestamp.","operationId":"getUserCombatSpecials","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","maximum":9223372036854775807,"exclusiveMinimum":0,"description":"Torn player ID.","title":"Id"},"description":"Torn player ID."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CombatSpecials"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: path or query validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: player not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/faction/{id}/loadouts":{"get":{"tags":["Loadouts"],"summary":"Get faction member loadouts","description":"Returns the faction roster with each member's latest recorded loadout. Members without a recorded loadout have loadout=null. members_observed_at is the roster timestamp.","operationId":"getFactionLoadouts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","maximum":9223372036854775807,"exclusiveMinimum":0,"description":"Torn faction ID.","title":"Id"},"description":"Torn faction ID."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactionLoadouts"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: path or query validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: faction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/ranked-items":{"get":{"tags":["Ranked Items"],"summary":"Search ranked weapons and armor","description":"Search exact ranked weapon and armor instances. sort is required and filters are combined with AND. bonus1 and bonus2 accept a Torn bonus ID or case-insensitive bonus name. source filters by loadout or auction. Set include_total=true to include an exact match count. Reuse pagination.next_cursor with the same query. Invalid filter combinations return 422; no matches return items=[].","operationId":"searchRankedItems","parameters":[{"name":"sort","in":"query","required":true,"schema":{"enum":["name","rarity","damage","accuracy","armor","quality","bonus1","bonus2","auction_price","auction_ended_at"],"type":"string","description":"Sort by name, rarity, damage, accuracy, armor, quality, bonus1, bonus2, auction_price, or auction_ended_at.","title":"Sort"},"description":"Sort by name, rarity, damage, accuracy, armor, quality, bonus1, bonus2, auction_price, or auction_ended_at."},{"name":"category","in":"query","required":false,"schema":{"enum":["weapons","armor"],"type":"string","description":"Category: weapons or armor. Default: weapons.","default":"weapons","title":"Category"},"description":"Category: weapons or armor. Default: weapons."},{"name":"item_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":9223372036854775807,"exclusiveMinimum":0},{"type":"null"}],"description":"Torn base item ID.","title":"Item Id"},"description":"Torn base item ID."},{"name":"sub_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Item subtype, case-insensitive.","title":"Sub Type"},"description":"Item subtype, case-insensitive."},{"name":"slot","in":"query","required":false,"schema":{"anyOf":[{"enum":["primary","secondary","melee","body","temporary","helmet","pants","boots","gloves"],"type":"string"},{"type":"null"}],"description":"Equipment slot: primary, secondary, melee, body, temporary, helmet, pants, boots, or gloves.","title":"Slot"},"description":"Equipment slot: primary, secondary, melee, body, temporary, helmet, pants, boots, or gloves."},{"name":"armor_set","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Armor set name.","title":"Armor Set"},"description":"Armor set name."},{"name":"rarity","in":"query","required":false,"schema":{"anyOf":[{"enum":["red","orange","yellow"],"type":"string"},{"type":"null"}],"description":"Rarity: yellow, orange, or red.","title":"Rarity"},"description":"Rarity: yellow, orange, or red."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"enum":["loadout","auction"],"type":"string"},{"type":"null"}],"description":"Source: loadout or auction.","title":"Source"},"description":"Source: loadout or auction."},{"name":"bonus1","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Torn bonus ID or name. Names are case-insensitive; bonus1 and bonus2 are labels, not physical bonus positions.","title":"Bonus1"},"description":"Torn bonus ID or name. Names are case-insensitive; bonus1 and bonus2 are labels, not physical bonus positions."},{"name":"bonus1_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum bonus1 value. Requires bonus1.","title":"Bonus1 Min"},"description":"Minimum bonus1 value. Requires bonus1."},{"name":"bonus1_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum bonus1 value. Requires bonus1.","title":"Bonus1 Max"},"description":"Maximum bonus1 value. Requires bonus1."},{"name":"bonus2","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Torn bonus ID or name. Names are case-insensitive; bonus1 and bonus2 are labels, not physical bonus positions.","title":"Bonus2"},"description":"Torn bonus ID or name. Names are case-insensitive; bonus1 and bonus2 are labels, not physical bonus positions."},{"name":"bonus2_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum bonus2 value. Requires bonus2.","title":"Bonus2 Min"},"description":"Minimum bonus2 value. Requires bonus2."},{"name":"bonus2_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum bonus2 value. Requires bonus2.","title":"Bonus2 Max"},"description":"Maximum bonus2 value. Requires bonus2."},{"name":"bonus_count","in":"query","required":false,"schema":{"anyOf":[{"enum":[1,2],"type":"integer"},{"type":"null"}],"description":"Number of bonuses: 1 or 2.","title":"Bonus Count"},"description":"Number of bonuses: 1 or 2."},{"name":"damage_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum damage.","title":"Damage Min"},"description":"Minimum damage."},{"name":"damage_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum damage.","title":"Damage Max"},"description":"Maximum damage."},{"name":"accuracy_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum accuracy.","title":"Accuracy Min"},"description":"Minimum accuracy."},{"name":"accuracy_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum accuracy.","title":"Accuracy Max"},"description":"Maximum accuracy."},{"name":"armor_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum armor.","title":"Armor Min"},"description":"Minimum armor."},{"name":"armor_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum armor.","title":"Armor Max"},"description":"Maximum armor."},{"name":"quality_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum quality.","title":"Quality Min"},"description":"Minimum quality."},{"name":"quality_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Maximum quality.","title":"Quality Max"},"description":"Maximum quality."},{"name":"auction_price_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":9223372036854775807,"minimum":0},{"type":"null"}],"description":"Minimum latest completed auction price.","title":"Auction Price Min"},"description":"Minimum latest completed auction price."},{"name":"auction_price_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":9223372036854775807,"minimum":0},{"type":"null"}],"description":"Maximum latest completed auction price.","title":"Auction Price Max"},"description":"Maximum latest completed auction price."},{"name":"auction_ended_after","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Latest completed auction ended at or after this Unix timestamp.","title":"Auction Ended After"},"description":"Latest completed auction ended at or after this Unix timestamp."},{"name":"auction_ended_before","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Latest completed auction ended at or before this Unix timestamp.","title":"Auction Ended Before"},"description":"Latest completed auction ended at or before this Unix timestamp."},{"name":"direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction: asc or desc. Default: desc.","default":"desc","title":"Direction"},"description":"Sort direction: asc or desc. Default: desc."},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","description":"Include exact match count. Default: false.","default":false,"title":"Include Total"},"description":"Include exact match count. Default: false."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Results per page, 1-100. Default: 25.","default":25,"title":"Limit"},"description":"Results per page, 1-100. Default: 25."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"pagination.next_cursor from the previous page.","title":"Cursor"},"description":"pagination.next_cursor from the previous page."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPage"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: invalid filter, selector, range, sort combination, or cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/items/{item}":{"get":{"tags":["Items"],"summary":"Get an exact item","description":"Looks up an exact item by KAL item_ref or a positive Torn owned-item UID. The response always uses item_ref as the item identifier.","operationId":"getItem","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"description":"KAL item_ref or positive Torn owned-item UID.","title":"Item"},"description":"KAL item_ref or positive Torn owned-item UID."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogItem"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: path or query validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}},"/items/{item}/history":{"get":{"tags":["Items"],"summary":"Get an item's history","description":"Returns loadout appearances and completed auction sales for an exact item, newest first. Omit source to include both. pagination.next_cursor pages through the history. A loadout event's loadout_cursor can be passed to /user/{user_id}/loadout?cursor=... to retrieve that loadout.","operationId":"getItemHistory","parameters":[{"name":"item","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"description":"KAL item_ref or positive Torn owned-item UID.","title":"Item"},"description":"KAL item_ref or positive Torn owned-item UID."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"enum":["loadout","auction"],"type":"string"},{"type":"null"}],"description":"loadout or auction. Omit to include both.","title":"Source"},"description":"loadout or auction. Omit to include both."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Events per page, 1-50. Default: 25.","default":25,"title":"Limit"},"description":"Events per page, 1-50. Default: 25."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"pagination.next_cursor from the previous page.","title":"Cursor"},"description":"pagination.next_cursor from the previous page."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Torn API key. Optional when the Authorization header is used.","title":"Key"},"description":"Torn API key. Optional when the Authorization header is used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemHistory"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"400":{"description":"Code 3: conflicting API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"description":"Codes 1-2: API key required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"403":{"description":"Codes 4-6: access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"422":{"description":"Code 11: path or query validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"429":{"description":"Code 20: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"503":{"description":"Code 32: KAL is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"404":{"description":"Code 13: item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"x-stability":"Beta","security":[{"api_key":[]}]}}},"components":{"schemas":{"APIError":{"properties":{"code":{"type":"integer","title":"Code","description":"Numeric KAL error code."},"error":{"type":"string","title":"Error","description":"Error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details, when available."}},"type":"object","required":["code","error"],"title":"PublicAPIError","description":"Standard KAL API error response."},"Ammo":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id","description":"Torn ammo ID, if known."},"category_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Category Id","description":"Torn ammo category ID, if known."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Ammo type, if known."}},"type":"object","required":["id","category_id","type"],"title":"PublicAmmo"},"AuctionHistoryEvent":{"properties":{"type":{"type":"string","const":"auction","title":"Type","description":"Event type."},"listing_id":{"type":"integer","title":"Listing Id","description":"Torn auction listing ID."},"ended_at":{"type":"integer","title":"Ended At","description":"Unix timestamp in seconds when the auction ended."},"price":{"type":"integer","minimum":0.0,"title":"Price","description":"Final recorded auction price."},"bids":{"type":"integer","minimum":0.0,"title":"Bids","description":"Recorded number of bids."},"seller_id":{"type":"integer","title":"Seller Id","description":"Torn ID of the recorded auction seller."},"buyer_id":{"type":"integer","title":"Buyer Id","description":"Torn ID of the recorded auction buyer."}},"type":"object","required":["type","listing_id","ended_at","price","bids","seller_id","buyer_id"],"title":"PublicAuctionHistoryEvent"},"AuctionSale":{"properties":{"listing_id":{"type":"integer","title":"Listing Id","description":"Torn auction listing ID."},"ended_at":{"type":"integer","title":"Ended At","description":"Unix timestamp in seconds when the auction ended."},"price":{"type":"integer","minimum":0.0,"title":"Price","description":"Final recorded auction price."},"bids":{"type":"integer","minimum":0.0,"title":"Bids","description":"Recorded number of bids on the completed auction."},"seller_id":{"type":"integer","title":"Seller Id","description":"Torn ID of the recorded auction seller."},"buyer_id":{"type":"integer","title":"Buyer Id","description":"Torn ID of the recorded auction buyer."}},"type":"object","required":["listing_id","ended_at","price","bids","seller_id","buyer_id"],"title":"PublicAuctionSale"},"AuctionSource":{"properties":{"type":{"type":"string","const":"auction","title":"Type","description":"Source type."},"latest_sale":{"$ref":"#/components/schemas/AuctionSale","description":"Most recent completed auction sale for this item."}},"type":"object","required":["type","latest_sale"],"title":"PublicAuctionSource"},"Bonus":{"properties":{"id":{"type":"integer","title":"Id","description":"Official Torn bonus ID."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Bonus name, if known."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Bonus description, if known."},"value":{"type":"number","title":"Value","description":"Bonus value for this item."},"rarity":{"anyOf":[{"type":"string","enum":["yellow","orange","red"]},{"type":"null"}],"title":"Rarity","description":"KAL rarity tier for this bonus roll: yellow, orange, red, or null."}},"type":"object","required":["id","title","description","value","rarity"],"title":"PublicBonus"},"CatalogAppearance":{"properties":{"user_id":{"type":"integer","title":"User Id","description":"Torn player ID for the latest recorded appearance."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Player name, if known."},"slot":{"type":"integer","exclusiveMinimum":0.0,"title":"Slot","description":"Torn equipment slot number for this appearance."},"slot_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slot Name","description":"Equipment slot name for this appearance, if known."},"observed_at":{"type":"integer","title":"Observed At","description":"Latest appearance time as Unix seconds."}},"type":"object","required":["user_id","name","slot","slot_name","observed_at"],"title":"PublicCatalogAppearance"},"CatalogItem":{"properties":{"item_ref":{"type":"string","title":"Item Ref","description":"KAL identifier for this exact item instance."},"id":{"type":"integer","title":"Id","description":"Torn base item ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Item name, if known."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Torn item type, if known."},"sub_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Type","description":"Torn item subtype, if known."},"stats":{"anyOf":[{"$ref":"#/components/schemas/ItemStats"},{"type":"null"}],"description":"Item stats, if applicable."},"bonuses":{"items":{"$ref":"#/components/schemas/Bonus"},"type":"array","title":"Bonuses","description":"Torn bonuses on this item."},"rarity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rarity","description":"Ranked-item rarity, or null."},"slot":{"type":"integer","exclusiveMinimum":0.0,"title":"Slot","description":"Torn equipment slot number."},"slot_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slot Name","description":"Equipment slot name, if known."},"sources":{"items":{"oneOf":[{"$ref":"#/components/schemas/LoadoutSource"},{"$ref":"#/components/schemas/AuctionSource"}],"discriminator":{"propertyName":"type","mapping":{"auction":"#/components/schemas/PublicAuctionSource","loadout":"#/components/schemas/PublicLoadoutSource"}}},"type":"array","minItems":1,"title":"Sources","description":"Sources available for this item."}},"type":"object","required":["item_ref","id","name","type","sub_type","stats","bonuses","rarity","slot","slot_name","sources"],"title":"PublicCatalogItem"},"CatalogPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CatalogItem"},"type":"array","title":"Items","description":"Exact item instances matching the query."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Exact match count when include_total=true; otherwise null."},"pagination":{"$ref":"#/components/schemas/CursorPagination","description":"Pagination for the next catalog page."}},"type":"object","required":["items","total","pagination"],"title":"PublicCatalogPage"},"CheckKeyResponse":{"properties":{"is_registered":{"type":"boolean","title":"Is Registered","description":"True if this Torn API key is registered with KAL."}},"type":"object","required":["is_registered"],"title":"PublicCheckKeyResponse"},"CombatSpecial":{"properties":{"name":{"type":"string","title":"Name","description":"Company special name."},"effect":{"type":"string","title":"Effect","description":"Human-readable combat-related effect."},"job_point_cost":{"type":"integer","title":"Job Point Cost","description":"Job-point cost for the special."},"required_star":{"type":"integer","title":"Required Star","description":"Required company star rating."}},"type":"object","required":["name","effect","job_point_cost","required_star"],"title":"PublicCombatSpecial"},"CombatSpecials":{"properties":{"user_id":{"type":"integer","title":"User Id","description":"Torn player ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Player name, if known."},"updated_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Updated At","description":"Employment data timestamp as Unix seconds."},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name, if known."},"company_type_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Company Type Id","description":"Torn company type ID, if known."},"company_rating":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Company Rating","description":"Company star rating, if known."},"specials":{"items":{"$ref":"#/components/schemas/CombatSpecial"},"type":"array","title":"Specials","description":"Combat-related specials available from the company type and rating."}},"type":"object","required":["user_id","name","updated_at","company_name","company_type_id","company_rating","specials"],"title":"PublicCombatSpecials"},"CursorPagination":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for the next page, or null at the end."}},"type":"object","required":["next_cursor"],"title":"PublicCursorPagination"},"Equipment":{"properties":{"id":{"type":"integer","title":"Id","description":"Torn base item ID."},"item_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Ref","description":"KAL identifier for this exact item, or null when there is no instance reference."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Item name, if known."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Torn item type, if known."},"sub_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Type","description":"Torn item subtype, if known."},"stats":{"anyOf":[{"$ref":"#/components/schemas/ItemStats"},{"type":"null"}],"description":"Damage, accuracy, armor, and quality stats."},"bonuses":{"items":{"$ref":"#/components/schemas/Bonus"},"type":"array","title":"Bonuses","description":"Torn bonuses on this item."},"rarity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rarity","description":"Ranked-item rarity, or null."},"slot":{"type":"integer","exclusiveMinimum":0.0,"title":"Slot","description":"Torn equipment slot number."},"slot_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slot Name","description":"Equipment slot name, if known."},"ammo":{"anyOf":[{"$ref":"#/components/schemas/Ammo"},{"type":"null"}],"description":"Ammo information, if available."},"mods":{"items":{"$ref":"#/components/schemas/Mod"},"type":"array","title":"Mods","description":"Weapon mods."},"effect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effect","description":"Item effect, if present."},"blocked_effects":{"items":{"type":"string"},"type":"array","title":"Blocked Effects","description":"Blocked armor effects."}},"type":"object","required":["id","item_ref","name","type","sub_type","stats","bonuses","rarity","slot","slot_name","ammo","mods","effect","blocked_effects"],"title":"PublicEquipment"},"FactionLoadouts":{"properties":{"faction_id":{"type":"integer","title":"Faction Id","description":"Torn faction ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Faction name, if known."},"tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag","description":"Faction tag, if known."},"members_observed_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Members Observed At","description":"Faction roster timestamp as Unix seconds."},"members":{"items":{"$ref":"#/components/schemas/FactionMember"},"type":"array","title":"Members","description":"Faction members."}},"type":"object","required":["faction_id","name","tag","members_observed_at","members"],"title":"PublicFactionLoadouts"},"FactionMember":{"properties":{"user_id":{"type":"integer","title":"User Id","description":"Torn player ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Player name, if known."},"loadout":{"anyOf":[{"$ref":"#/components/schemas/LoadoutRecord"},{"type":"null"}],"description":"Latest recorded loadout, or null if none is available."}},"type":"object","required":["user_id","name","loadout"],"title":"PublicFactionMember"},"ItemHistory":{"properties":{"item_ref":{"type":"string","title":"Item Ref","description":"KAL identifier for this exact item."},"history":{"items":{"oneOf":[{"$ref":"#/components/schemas/LoadoutHistoryEvent"},{"$ref":"#/components/schemas/AuctionHistoryEvent"}],"discriminator":{"propertyName":"type","mapping":{"auction":"#/components/schemas/PublicAuctionHistoryEvent","loadout":"#/components/schemas/PublicLoadoutHistoryEvent"}}},"type":"array","title":"History","description":"Loadout and auction events ordered newest first."},"pagination":{"$ref":"#/components/schemas/CursorPagination","description":"Pagination for older history events."}},"type":"object","required":["item_ref","history","pagination"],"title":"PublicItemHistory"},"ItemStats":{"properties":{"damage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Damage","description":"Damage stat, if applicable."},"accuracy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Accuracy","description":"Accuracy stat, if applicable."},"armor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Armor","description":"Armor stat, if applicable."},"quality":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality","description":"Quality stat, if applicable."}},"type":"object","required":["damage","accuracy","armor","quality"],"title":"PublicItemStats"},"Loadout":{"properties":{"observed_at":{"type":"integer","title":"Observed At","description":"Loadout observation time as Unix seconds."},"equipment":{"items":{"$ref":"#/components/schemas/Equipment"},"type":"array","title":"Equipment","description":"Equipped items; empty equipment slots are omitted."},"user_id":{"type":"integer","title":"User Id","description":"Torn player ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Player name, if known."},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination for older distinct loadouts."}},"type":"object","required":["observed_at","equipment","user_id","name","pagination"],"title":"PublicLoadout"},"LoadoutHistoryEvent":{"properties":{"type":{"type":"string","const":"loadout","title":"Type","description":"Event type."},"user_id":{"type":"integer","title":"User Id","description":"Torn player ID for this appearance."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Player name, if known."},"slot":{"type":"integer","exclusiveMinimum":0.0,"title":"Slot","description":"Torn equipment slot number for this appearance."},"slot_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slot Name","description":"Equipment slot name for this appearance, if known."},"observed_at":{"type":"integer","title":"Observed At","description":"Appearance time as Unix seconds."},"loadout_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Loadout Cursor","description":"Cursor for the loadout containing this appearance. Pass it as cursor to /user/{user_id}/loadout."}},"type":"object","required":["type","user_id","name","slot","slot_name","observed_at","loadout_cursor"],"title":"PublicLoadoutHistoryEvent"},"LoadoutRecord":{"properties":{"observed_at":{"type":"integer","title":"Observed At","description":"Loadout observation time as Unix seconds."},"equipment":{"items":{"$ref":"#/components/schemas/Equipment"},"type":"array","title":"Equipment","description":"Equipped items; empty equipment slots are omitted."}},"type":"object","required":["observed_at","equipment"],"title":"PublicLoadoutRecord"},"LoadoutSource":{"properties":{"type":{"type":"string","const":"loadout","title":"Type","description":"Source type."},"latest_appearance":{"$ref":"#/components/schemas/CatalogAppearance","description":"Most recent loadout appearance for this item."}},"type":"object","required":["type","latest_appearance"],"title":"PublicLoadoutSource"},"Mod":{"properties":{"id":{"type":"integer","title":"Id","description":"Official Torn mod ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Mod name, if known."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Mod description, if known."}},"type":"object","required":["id","name","description"],"title":"PublicMod"},"Pagination":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for the next older distinct loadout, or null at the end."}},"type":"object","required":["next_cursor"],"title":"PublicPagination"}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"Authorization","description":"Enter your Torn API key. Swagger adds the `ApiKey` prefix automatically. Outside Swagger, use `Authorization: ApiKey YOUR_TORN_API_KEY`. `?key=YOUR_TORN_API_KEY` is also supported."}}},"servers":[{"url":"https://api.kalends.dev","description":"KAL API host"}],"externalDocs":{"description":"Full KAL API documentation","url":"https://kalends.dev/api-docs"},"tags":[{"name":"Authentication","description":"API key checks."},{"name":"Loadouts","description":"Player and faction loadouts."},{"name":"Users","description":"Player data."},{"name":"Ranked Items","description":"Ranked weapon and armor search."},{"name":"Items","description":"Exact items and item history."}]}