Introduction

The goal of the Torn API is to provide a fully supported and read-only method for players to pull useful information from Torn about their player, faction, or company. This can be used individually to retrieve information about your account, or you can build a website that the entire community can use to do interesting things with the data exposed via the API.

Potential

Whether you're making a browser extension to aid factions during wartime, a mobile application to offer instant notifications, or a website to track data for graphing - the possibilities are endless - simply using the 16 character API keys. We encourage you to be creative, building features and tools that expand Torn's gameplay and enjoyment.

Acceptable usage

This system has been developed so that you should only ever need to request an API key from the user. All of the user's information can be obtained with just their key, there shouldn't be any requirement to ask for a name or user ID. Torn passwords should never be requested from any users, ever.

You must keep keys, and the data obtained from them, securely protected and confidential unless permitted by the key owner. By accepting other user's keys, they are placing their trust in you - do not exploit this. We will permanently ban offending applications from accessing the API at a moment's notice.

We respectfully request that you follow Torn's no-advertising policy when building websites or applications that use our API system to ensure optimal user experience, however, exceptions can be made. Please contact us if you would like to advertise, accept voluntary real-money donations or charge users for usage.

Please make sure your scripts are optimised to retrieve only the information required for the specific request they're making. They should be retrieving as little information as possible; this will improve loading time and reduce stress on Torn's servers.

All scripts or tools must be compliant with the API Terms of Service Guidelines defined below.

API Terms of Service (ToS) Guidelines

When creating a script, userscript, sheet, extension, API service, bot, 3rd party website or any other API tool (collectively "service"), the end user must be aware of how will their API key be used.

Here's a table with the information that is important to the end user - giving them a good idea of what to expect from the API service they're using:

If the service is not storing or sharing the data or the key anywhere, it's enough to state so, otherwise ToS with the information above needs to be clearly and visibly stated in any place where user is providing their API key in the table format highlighted above.

When integrating your service with another service (opt-in), make sure there's at least a link to ToS of the service you're allowing the user to integrate with.

When integrating your service with another service (automatically), your ToS need to cover the usage of the service you're integrating with.

Using keys for purposes other than the ones described in the ToS or deceiving the end user into believing that the key is being used for a purpose other than described is prohibited and is a punishable offense.

These rules also apply to those who purchase API keys from other players.

If you're unsure how to describe your service, feel free to contact Torn staff.

If you suspect your key was misused, you can use 'key' -> 'log' selection to view & monitor API key usage history.

All services must be compliant with Torn's scripting rules.

ToS examples can be found at the bottom of this page.

Unfair advantage

We understand that crafting an API system for Torn could give some users an unfair advantage. We want the system to expand & enhance gameplay rather than giving users an advantage which makes it easier to compete against others. We have taken this into account during development, but we will be listening to feedback and making any appropriate changes that are required.

Logging

Please be aware, we log all details and inputs of requests and make routine checks. If misuse occurs, we will permanently ban IP addresses, keys, and users from accessing the system without notice.

Automatic limits & blocks

Key limits

Each user can make up to 100 individual requests per minute across all of their keys, this should be more than enough for almost anything to be achievable. Multiple requests using invalid keys may result in a temporary IP ban - you must account for this by removing disabled or invalid keys upon error.

IP limits

Services which have accumulated a large number of keys may be subject to a different limit: 5,000 requests per minute per IP address, regardless of how many keys are used from that address.

This limit must not be bypassed by using multiple servers. Services bypassing it may be blocked without notice, and the service owners may have their accounts terminated. If you are nearing this limit, please contact Torn staff and let them know about your usage.

These limits may also change without notice to ensure the Torn servers remain stable.

Cache

There are two different types of cache in the works.

Service cache

All API requests are cached by the service, and this cache can last up to 30 seconds. With this type of cache, two subsequent, identical requests, will return the same data. The purpose of this cache is to simply to reduce the server load because multiple tools/websites/scripts/etc. might request the same data nearly at the same time, and there's usually no need to process these requests individually.

However, this can sometimes become a nuisance, because in some cases you might need fresh information. Because of this, everyone is free to bypass this cache by using e.g. timestamp query parameter to make their request unique (comment query parameter is ignored for this) whenever they need to.

Requests which hit the service cache are not consuming the API key quota.

Global cache

Several selections are cached globally. This means, all users who request these selections will get the same data, regardless of the API key used or if their request is unique. This type of cache is set on the server-side, and simply cannot be bypassed.

The main purpose of this cache is to prevent the potential unfair advantage certain selections could introduce. There is only a handful of selections which are utilizing this type of cache.

Current globally cached selections are:

• 'market' -> 'itemmarket'
• 'market' -> 'properties'
• 'market' -> 'rentals'
• 'company' -> 'companies'
• 'user' -> 'bazaar'
• 'torn' -> 'bounties'
• 'user' -> 'bounties'

Selection access levels

API keys can have one of four different access levels, this will limit which selections they're able to access. We've assigned access level requirements to every selection, these are visible in the table below.

Error codes

API Terms of Service Examples

Example No. 1

Description: a 3rd party website utilizing 'user' -> 'log' selection to show detailed statistics for certain gameplay areas which stores key or data only in the user's browser.

ToS: You maintain full control of your data; everything is stored in your browser. No data is sent anywhere.

For such websites, ToS in the table format is not necessary, but might be useful to end users and could look something like this:

Example No. 2

Description: a 3rd party website sharing personal data between faction members. The website stores API key and private user information in its own database.

ToS:

Example No. 3

Description: a browser extension providing notifications based on cooldowns and other user's activity which allows fully opt-in integration with other services.

ToS: You maintain full control of your data; everything is stored in your browser. No data is sent anywhere. You can view our detailed API usage here : link_to_api_usage_page

[] Service XYZ: Check the checkbox to integrate Service XYZ. Terms of Service for XYZ can be found here: link_to_XYZ_tos

[] Service ZZZ: Check the checkbox to integrate Service ZZZ. Terms of Service for ZZZ can be found here: link_to_ZZZ_tos

For such extension, ToS in the table format is not necessary, but might be useful to end users and could look something like this:

Example No. 4

Description: a google sheet pulling current plushie/flower prices.

ToS:

Example No. 5

Description: a discord faction bot where submitted API key is used to fetch data for other services.

ToS: