Upcoming API changes

Hey everyone, 

I added two new selections today:

• 'user' -> 'organizedcrime' which returns information about the organized crime key owner is currently participating in (if any)
• 'user' -> 'factionbalance' which returns key owner's current faction balance (if they're in a faction)

I also added 'executed_at' field to 'faction' -> 'crimes' (and 'user' -> 'organizedcrime') which indicates when was the crime actually executed at. Unfortunately, this value will be "null" for all crimes executed until today (I'll see if we can somehow backfill the missing data).

Upcoming breaking change notice!

Early next week (Monday or Tuesday), we'll be changing the required access key type, for these selections:

• 'user' -> 'newmessages' selection to require Limited access key (currently Public)
• 'user' -> 'newevents' selection to require Minimal access key (currently Public)

This should improve the privacy concerns some users had while sharing their public keys.

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Let me know your thoughts in the discussion thread. 

Thank you.

Hey all, 

Today I finally added 'user' -> 'attacks' & 'user' -> 'attacksfull' to Swagger and API v2.

The results have the same structure as 'faction' -> 'attacks' & 'faction' -> 'attacksfull'.

Both of these selections are now available in Swagger (if you're not seeing changes make sure to hard-refresh the openapi.json file) which should now have endpoints ordered alphabetically (and all other non-section tags removed to reduce clutter). 

But if you'd like, I can re-add the tags I removed?

Let me know your thoughts in the discussion thread. 

Thank you.

Hey everyone, 

After Pavel made some backend modifications in the attacking logic, I was able to add 'finishing_hit_effects" to 'user' -> 'attacks' & 'faction' -> 'attacks' selections, but unfortunately these won't work retroactively. 

I added finishing hit effects as a separate object instead of adding the values into the 'modifiers' object.

The reasoning for that is the following - currently, the 'modifiers' object only shows respect related modifiers, so I would either have to wrap those modifiers into a new object 'respect' and then add other modifiers (e.g. 'hospital_time', 'experience' etc.), which would be a breaking change.
Additionally, the 'revitalize' modifier would need to either be true/false or return 0/1, unlike all other modifiers which start with 1, so it made sense to put these values as a separate object.

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If you disagree, or see room for improvement, please let me know in the discussion thread. 

Thank you.

Hey,

Small update today - I've made some improvements to pre-flight OPTIONS requests when setting API keys in the Authorization header. 

More info in this comment: https://www.torn.com/forums.php#/p=threads&f=63&t=16436663&b=0&a=0&start=40&to=25577460 

Additionally, last week's change was made live:

• 'user' -> 'newmessages' & 'user' -> 'newevents' now both require Limited access API key (or above) instead of Public one

Thanks!

Hey everyone,

A few updates today:

• Added OC payouts to 'faction' -> 'crimes' in API v2
• Reworked 'faction' -> 'rankedwars' & 'torn' -> 'rankedwars' to be one selection ('faction' -> 'rankedwars') in API v2
• Added 'faction' -> 'rankedwarreport' in API v2 which replaces 'torn' -> 'rankedwarreport' 
• Closed 'torn' -> 'rankedwars' & 'torn' -> 'rankedwarreport' in API v2

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Let me know your thoughts in the discussion thread. 

Thank you.

Hey everyone,

Sorry for the late announcement. 

I've created a new selection 'torn' -> 'attacklog' in API v2 with which you're now able to get full attack logs via API!

The best way to get full logs of larger group fights is to use "_metadata" links. There should be 100 rows / request, but unfortunately that's not always the case due to system limitations.

All stealth attacks have the attacker hidden, even if you're the attacker viewing the log. That was done on purpose to protect the anonymity of players. If there will be a need, it will be possible to create 'user' -> 'attacklog' selection where you could see non-stealthed logs, but I don't see big use case for these currently. 

In other news, 'user' -> 'itemmarket' & 'user' -> 'personalstats' selections are now tagged as "Stable".

If you notice anything that's off (as @Stig has already done) let me know in the discussion thread. 

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Thank you!

Hey everyone,

Three new items related selections are now available in API v2. They are: 

• 'torn' -> 'items', where you can get mulitple items at once by passing ids or certain item categories (or all of them), and you can now also change the direction (ascending, descending)
• 'torn' -> 'itemammo' which returns information about ammo
• 'torn' -> 'itemmods' which returns mods that can be purchased as mission rewards

I'm hoping to also build 'torn' -> 'itemeffects' soon as well.

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something to be improved in the discussion thread. 

Thank you.

Hey everyone, 

Today, all the reviving sections got revived, both faction & user: 

• 'user' -> 'revives' is now available via Swagger
• 'user' -> 'revivesfull' is now available via Swagger
• 'faction' -> 'revives' is now available via Swagger
• 'faction' -> 'revivesfull' is now available via Swagger

There isn't something specially added to these selections - they mostly have improved structure, but you can now pass "stripTags=true" query parameter in order to remove HTML tags from the hospital reason (that's also the default behaviour). 

In other news:

• there was a small bug in the new 'torn' -> 'items' selection not working when only passing one id (now fixed)
• in the 'faction' -> 'chain', the 'cooldown' value is now set to 0 if the chain is not in the cooldown
• 'faction' -> 'chain' is now marked as "Stable"
• 'faction' -> 'chains' is now marked as "Stable"
• 'faction' -> 'chainreport' is now marked as "Stable"
• 'faction' -> 'rankedwars' is now marked as "Stable"
• fixed various random errors that happened mostly to Glasnost only lol

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something to be improved in the discussion thread. 

Thank you.

Hey everyone, 

There have been a few smaller changes and bug fixes done these days:

• Removed weapon stats from armor & vice versa in 'torn' -> 'itemstats' in API v1. This was done to fix these two bugs: bug#1 & bug#2
• Improved time format in 'user' -> 'icons' so e.g. "0 days, 0 hours, 1 minutes and 30 seconds" is now shown as "1 minute and 30 second" instead of having values with zeroes
• Fixed incorrect type shown in API v2 in 'torn' -> 'items' - all non Weapon/Armor items had type set to "Item" instead of e.g. "Alcohol", "Booster", etc.  

Important deprecation notice!
Unfortunately, we need to remove 'life' from 'faction' -> 'members' for the time being. This will happen on 1st of May 2025.

It looks like this value is sometimes incorrect in our DB and requires re-calculation on every request - which is currently not done and and as a result, the value is sometimes shown incorrectly.

For each player, we'd have to check if they're reading a book, have Mao'l Tentacles item, if they have property, company & faction bonuses in order to calculate bonus life regeneration properly. 

This significantly impacts the performance of this selection, and without larger refactoring it's not really possible to show these values correctly (average request time increases for a full second on average).

There's this bug report for more information on the issue: https://www.torn.com/forums.php#/p=threads&f=19&t=16445744&b=0&a=0

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Let me know your thoughts in the discussion thread. 

Thank you.

Hey everyone, 

I have an important deprecation notice to announce regarding 'market' -> 'itemmarket' selection (which remains "Unstable").

Recent reports made us aware of a certain "underpriced items bot" which allows players to almost instantly purchase undervalued items off the item market without actually requiring the buyer to have the item market page opened & see what they're actually buying.

There are a few different versions of this bot - some rely on discord pings, others rely on websockets, but the most advanced ones are allowing players to "normally" play the game and be instantly notified about an undervalued item with a shortcut button to purchase it.

Because the 'market' -> 'itemmarket' selection returns listing ID for every item (unlike the old v1 API, which didn't), it's possible for these bots to operate via API as well. 

As such, we have no other choice, but to remove 'listing.id' from 'market' -> 'itemmarket' selection.

It's unlikely this change will magically remove all mug bots & underpriced bots, as some of them are working via websockets or use a different approach (e.g. advanced weapon bots match seller information based on armor/weapon stats & not listing ID), but this change aims to level the playing field for all players.


For those unaware there's also this bug opened for an issue with websockets that we're working on resolving.

It's also possible we'll simplify filters available in the 'market' -> 'itemmarket' selection in the future and completely remove the offset in order to make it possible to apply the 30s global cache, just like we did with 'user' -> 'bazaar' selection.

This change will take place on Monday, 3rd of March, 2025. 

Thanks!

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Let me know your thoughts in the discussion thread. 

Thank you.

Hey everyone, 

Today brings changes to the 'market' -> 'itemmarket' selection. I've managed to implement global 30s cache without removing the advanced filters. This means all players will receive the same response for a specific item for 30 seconds until the cache expires and the new set of entries is cached.

This also means it's not possible to bypass this global cache by using various "offset" values, keys or other query parameter values (unlike service cache which can be bypassed this way). 

As a result of these changes, I was able to increase the amount of rows returned to 100 across all items and add additional fields (quality and raw value for bonuses).

Additionally, considering the "listing id" value will become removed this upcoming Monday, I've set the "listing id" value to zero for all listings.

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If these changes broke something else by accident, please don't hesitate to let me know either in the discussion thread or bugs & issues forum. 

Thank you.

Hey everyone, 

I'm afraid the API progress was a bit slower this week as I was working on some other features. Here's a small EoW update:

There's now a new selection 'faction' -> 'crime' where you can pass a specific crime ID. This of course works only for crimes done in your own faction with a minimal API key with faction API permissions.

In other news:

• I've removed long deprecated "initiated_at" field from 'faction' -> 'crimes' selection (deprecation notice here: https://www.torn.com/forums.php#/p=threads&f=63&t=16401584&b=0&a=0&start=260&to=25530374)
• I've removed recently deprecated "id" field from 'market' -> 'itemmarket' selection (deprecation notice here: https://www.torn.com/forums.php#/p=threads&f=63&t=16401584&b=0&a=0&start=280&to=25673731)
• These selections are now marked as "Stable": 'faction' -> 'crimes', 'faction' -> 'crime', 'user' -> 'organizedcrime'

Deprecation notice!

The 'success_chance' field is now deprecated from organized crimes related selections. It's being replaced with the 'crime_pass_rate' field to match naming on site.

Future plans include adding user status (injured, hospitalized, jailed, successful) and if item was consumed to organized crimes related selections. 
After that, the plan is to finish the remaining faction related selections and move to property/user selections.

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If these changes broke something else by accident, please don't hesitate to let me know either in the discussion thread or bugs & issues forum. 

Thank you.

Hey everyone,

New friends/enemies/targets list API is now available under 'user' -> 'list'. It requires "Limited" or higher API key.

You can only request one category at the time and you can get up to 50 players from your list in one API call - most players will need just a few API calls to get their full lists, but few individuals with lists over 500 players on them will have to make a bit more requests...

Description has not been added in order to protect potential personal information. 

https://www.torn.com/swagger.php#/User/get_user_list 

Let me know if you'd like something else added to this selection!

EDIT:

In other news, this is now also fixed: https://www.torn.com/forums.php#/p=threads&f=19&t=16454994&b=0&a=0 

So if you're using "_metadata.prev" and "_metadata.next" please make sure to use "_metadata.links.prev" and "_metadata.links.next" from now on.

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If these changes broke something else by accident, please don't hesitate to let me know either in the discussion thread or bugs & issues forum. 

Thank you.

Hey everyone,

Some crimes 2.0 API improvements are finally here:

• Added 'scope' to 'rewards'
• Added 'outcome' to 'slots.user' (possible values are: "Successful", "Failed", "Jailed", "Injured", "Hospitalized")
• Added 'checkpoint_pass_rate' which replaces both 'crime_pass_rate' and 'success_chance' (both are deprecated and planned to be removed on 1st of May)
• Marked 'user_id' in 'slots' as deprecated (planned to be removed on 1st of May) because there's 'slot.user.id'
• Marked all fields in FactionCrime schema as 'required' (now have red asterix in Swagger)
• Added missing 'id' to 'ammo' in TornItemWeaponDetails
  
• And finally, what many are looking forward to - 'checkpoint_pass_rate' now returns CPR for the key owner on the available slots instead of 0 (expired crimes will still show value 0)

Load image


Upcoming Swaggger updates - I'll take some time to mark fields as required (seems to cause some code-gen issues), improve format of integers in schema and improve "allOf" types. 

I will also probably re-add keys as query parameters (optional) for those who wish to use that instead of headers.

--

The Swagger schema is updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If these changes broke something else by accident, please don't hesitate to let me know either in the discussion thread or bugs & issues forum. 

Thank you.

Hey everyone,

Today brings only Swagger schema updates. The summary is:

• OpenAPI upgraded from 3.0.x to 3.1.x
• All integers now have format - 'int32' or 'int64'
• The majority of fields (~98%) is now marked as 'required'
• Replaced 'Stable' & 'Unstable' tags with vendor extension 'x-stability' (values "Stable" and "Unstable")
• Marked revives related selections as "Stable" 
• Fixed 'nullable' objects (now they're either the defined type or 'null')
• Deprecation warning! Added 'item_details' to 'ItemMarketListingNonstackable' object instead of 'itemDetails' (now deprecated)

These changes may have unintentionally caused other problems, so if you see something that's wrong or should be fixed, please do let me know in the discussion thread or bugs & issues forum.

--

The Swagger schema is updated (if you're not seeing changes make sure to hard-refresh the openapi.json file).

If these changes broke something else by accident, please don't hesitate to let me know either in the discussion thread or bugs & issues forum. 

Thank you.

Hey everyone,

There's a new selection 'faction' -> 'balance' now available in API v2. 

This selection basically unifies 'faction' -> 'donations' & 'faction' -> 'currency' into a single selection.
Additionally, current faction 'scope' is also added to this new selection.

In other news, 'user' -> 'organizedcrime' will now return error code 27 with the message "Must be migrated to organized crimes 2.0" if the faction did not switch to OC's 2.0 yet.
This should help with distinguishing between OC's 1.0 and 2.0 (if the user is not in OC, but the faction switched to OC's 2.0 it will return 'null' response).

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something to be improved in the discussion thread. 

Thank you.

Hey everyone, 

There's an important upcoming change for 'user' -> 'log' selection.

It will be possible to only request this selection separately in the near future, and no longer together with other selections. So, this will work:

https://api.torn.com/user/selections=log&key=

But this will no longer work (log results will be simply omitted): 
https://api.torn.com/user/selections=cooldowns,icons,profile,bars,notifications,log,events,messages&key=

The reason for this change is just to make everything a bit more cost-effective.
Some tools are unnecessary requesting "log" selection in every request, which means every request does 100 (often unnecessary, duplicated) reads from the FireStore. 

That multiplied with hundreds of thousands requests daily can become unnecessary pricey. 

That said - you probably don't have to worry about anything.

Tools and 3rd party websites that rely on 'user' -> 'log' selection like TornReport shouldn't be impacted by this change and I am sure you can still continue to use them normally. The impact they make is still very minor in the grand scheme of things, but i just wanted to share the reasoning behind this upcoming change.

This change is planned to go out on June 1st, 2025.

Thanks!

Hey everyone, 

Faction upgrades & stats selections got revived today:

• 'torn' -> 'factiontree' now has improved structure (I hope) with challenge values shown as integers and stat required field
• 'faction' -> 'upgrades' now doesn't have duplicate branches (core branches are separate)
• 'faction' -> 'contributors' now accepts 'cat' parameter with values 'all' & 'current' (default 'current'). The option 'all' will return everyone who ever contributed, and the faction 'current' will only return current member's contributions. There's also a required query parameter 'stat' (same enum values as the ones from 'torn' -> 'factiontree')
• 'faction' -> 'stats' now has slightly changed structure (also utilizes new enum values)

Let me know if something's not right or if you're experiencing any issues with anything in the discussion thread.

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something to be improved in the discussion thread. 

Thank you.

Hey everyone,

The 'faction' -> 'positions' selection is now updated as well. The structure of this selection is changed a bit compared to v1. Each position now holds an array of "abilities" (enum values).

This has been added to Swagger as well:

https://www.torn.com/swagger.php#/Faction/get_faction_positions

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something to be improved in the discussion thread. 

Thank you.

Hey everyone,

Territory related selections are now refactored:

• 'torn' -> 'territory' : now only returns static information for every territory. The limit has been increased to 250 rows per request. This selection won't return rackets or faction ownership anymore - there are dedicated selections for that for those who wish to track factions movement on the map. It's also possible to get multiple territories by passing names as ids just like in API v1
• 'faction' -> 'territory' : returns all territories faction has with any rackets on it. Not many changes there except for the improved rackets payload
• 'faction' -> 'territoryownership' : returns information about faction ownership (who & when) on a territory. This returns up to 500 rows per request now, so it will be possible to get full territory ownership in just 9 requests now
• 'faction' -> 'rackets' : this replaces 'torn' -> 'rackets' and provides improved rewards data
• 'faction' -> 'territorywars' : can be used to get territory wars history for your own or a specific faction. It also returns currently ongoing territory wars, or a list of finished wars. The payload depends on the request (there's a small difference between ongoing and finished wars)
• 'faction' -> 'territorywarreport' : Has slightly improved structure

In other news: 

• There was a small bug in 'racing' -> 'tracks' where description field had an extra space in response
• The 'non-attackers' field in 'faction' -> 'chainreport' selection is now deprecated. It's being replaced with 'non_attackers' field and will be removed on 1st of June 2025
• The 'sci-fi' field in 'user' -> 'crimes' selection is now deprecated. It's being replaced with 'sci_fi' field and will be removed on 1st of June 2025
• The 'co-leader_id' field in 'faction' -> 'basic' selection is now deprecated. It's being replaced with 'co_leader_id' and will be removed on 1st of June 2025

Thanks @Tiksan for pointing those inconsistencies out. 

--

The Swagger schema is now updated as well (if you're not seeing changes make sure to hard-refresh the openapi.json file).

Please let me know if you encounter any bugs or would like something improved in the discussion thread. 

Thank you.