Minor improvement - Player revivable status

Current - When an API call is made to check if a player can be revived (even if they are not in hospital) currently the output is 1 or 0, based on the target's setting of Nobody / Everyone / Friends & Faction, with Friends & Family being in the target has the API key owner as a friend, or if they are from the same faction

Improvement - return either an integer value, 0 (Nobody), 1 (Friend & Faction), 2 (Everyone) or return the strings. Return the highest value. If I check with my key and a faction member has the value set to Everyone, I should be returned 2 or Everyone

Reasons - When in ranked wars, factions regularly check their own faction to see if their members have left revives enabled.
With the current system, you either use your own API keys (from within the faction) and get false positives or you use someone else's key (still with some false positives as they might be friends with the target) to check either the complete faction's member list or you use a hybrid of both, using your own key to get an initial list and then cross reference with someone else's key (reducing load on other person's key but increasing the total numer of API calls)

New feature request - Add User-related crime data in v2

Currently, there exist different endpoints for "global crime state", namely torn>searchforcash and torn>shoplifting.

This is good for knowing which uniques could be gotten, but that's about it.

I would like an endpoint like user>crimes, so that user-specific state can be evaluated.

Why do I need it?

There is a lot of, let's call it data analysis, you can do with real-time-ish data.

For example, YATA could give you an estimate when you can claim your "250 details in 1 card skimmer" honor based on the state of your card skimmers.

Another use case can be some sort of notification system for when a card skimmer gets found.

It could also make a shopping list for your current forgery projects, and once inventory api is back, check if you need to buy some items.

The list is practically endless, and with 19 more crimes coming, will be even longer. The spreadsheet people can have a field day :D

This data is also already available, but for automated means inaccessible due to the scripting rules. The so called "crimesHubApi" returns user and global state of the crimes system. I would argue that most work was already done, it "just" needs to follow new v2 naming standards. The crimesHubApi is the base for showing the icons on the crime hub. 

What could be drawbacks?

- Until all crimes are released, there will have to be (ir)regular changes applied to this endpoint. 

- As I said, the current implementation does not follow v2 naming standards.

- The data would be available in the crimeHubApi (which does not fall under the API ratelimits) and the normal api (with its ratelimits), so there might be double the maintenance work associated with that.

- IIRC, Ched said something about crimes not being a real time system, and things being generated "once you looked". I'm not sure how true this statement still is (and if the crimesHubApi is the thing that triggers it), but this might lead to only stale data being able to be read.

- The data is highly irregular from crime to crime.

Example:

I'll point to the existing URL, but because I don't want to post my CF api key, you can find your personal links by being at loader.php?sid=crimes and looking in the dev tools. The URL looks like this:

https://www.torn.com/crimesHubApi.php?userID=2780600&apiKey=XXX&rfcv=YYY

(the crimeHubApi uses the typeID parameter to only load one crime at the time, but this is optional. Check it out without a typeID, ty!)

New Feature request - OAUTH2

Now it's worth noting this might be outside the current purview of API v2, but I want to get a bit of publicity on this so (potentially) at some point something could be done.

I would like some form of OAUTH2 support for the API to enable "Login with Torn".

The bearer/access token would be used in API calls (like a normal API key) and the refresh token would be used to obtain a new access token when it expires (as normal OAUTH2 works).

It would be great if (similar to API permissions) custom permissions could be requested when setting up the app (so on prompt it would say "Do you want to login to MyService as ?" "This will give MyService access to the following data: ..."

Why do we (the developer community) need this?

One major "lacking" point when creating apps is the inherent insecurity of "verifying" someone is who they say they are.

Take the (fairly standard) login with API (for example what torn.report, tornexchange, and yata use). When a user logs in, there is no way to "know" for sure they are actually the user they say they are. I could share my API with a 3rd party service, then my key could be used to login as me (with or without my permission, there's no way to know).

"Login with key" also is just confusing for users who don't know much about the API. I have had many cases where I have had to explain to someone what the API is, what data the particular key gives access to, if its secure, etc.

Another example of login is "Login with Discord" which allows for (better) verification of identity (except not really due to a bug that was published about a month ago about how this is not actually true) but the downside is you still need to ask for an API token.

A third way to do it is having a standard login (username/password) then tie an API key to the account. This has no real benefits other than needing more secure credentials to login.

How would this benefit the community?

This would drastically cut down on any "confusion" as well as make login more secure. Login would be streamlined (don't need to redirect to API page, tell the user to copy the key, come back and paste), and by standardizing around one method (that checks all the boxes), it cuts down on the need for many different methods of authentication.

This also has a bonus of standardizing around "the standard". OAUTH2 is the industry standard protocol for authentication. And by adding this, it would allow 3rd party tools better integration, presenting a better user experience.

What are drawbacks?

The primary drawback is time. While there are standardized libraries for OAUTH2, there would need to be a new UI component (to show current connections), some "portal" where developers could manage their app_id/name (this could be as simple as a API endpoint with no UI, or a subpage in the OAUTH2 settings page).

That having been said, while there is definitely overhead in creating this, the pros would drastically improve the way users interact with 3rd party apps.

I actually strongly disagree with this as written. The data your talking about is private to the user, and is not "knowable" by a 3rd party user (someone in your opponents faction for example).

That having been said, your 100% right that having this data would be extremely useful for faction leaders. I would like to suggest a minor improvement to create a new faction->reviveStatus endpoint (only available to those with faction API access) to get the current revive status of each faction member all at once.

This has a few benefits:
Allows for quick checking of revive status for your whole faction

Maintains privacy for users, meaning that no new data is exposed to 3rd parties.

Now there is an argument to be made that it does not matter if a 3rd party could "know" this, since its not really useful information on its own. But its worth maintaining that the API does not give any "new" information that is not available through the site

Suggestion type:

 - General improvement (accross multiple endpoints)

What needs to be done:

- Armourynews, attacknews, and various other ‘news’ endpoints be rebuilt entirely to provide non-html data.
- Have weapon / item UID’s added to various locations, such as armorynews and armory endpoints

Why do you need this:

- It can be inconsistent to parse on our side, and requires us to know all types of the log to be able to parse it correctly in some cases.

Consider any drawbacks of your suggestion:

- None that I can think of

Examples:

[Armorynews]

{
"armorynews": {
"ml4H2HEDR4XSC1op5SlI": {"news": "Stig [2648238] deposited a Gold Plated AK-47.",
"uid": 123,
"timestamp": 1708597707
}
}
}

This could be made more indepth by including ‘player’ or something and ‘target’ and more data about the item used etc.

[Armory]

{
"weapons": [
{
"ID": 108,
"name": "9mm Uzi",
"type": "Primary",
"quantity": 3,
"available": 3,
"loaned": 0,
"loaned_to": null
"uids": [1, 2, 3]
},
]
}

Im not sure how we would signify which weapons have been loaned etc. Perhaps having each weapon in a list, instead of them being grouped is more appropriate. 

I wanted to say the same - I don't think this should be public information, but I do think this could be added to the faction API (I don't think adding to "users" section would be beneficial in any way though). 
But again, because currently, this is player personal information, maybe it will be necessary to first add an additional setting like:



Otherwise that sounds like a good idea to me (also because basically only player's factions would benefit from this, and I would argue that if you're in a faction in the first place you're there to "serve" (while getting something in return ofc)).

@Wootty2000 I'll keep you (and everyone else) updated on what's decided on this one. 

- IIRC, Ched said something about crimes not being a real time system, and things being generated "once you looked". I'm not sure how true this statement still is (and if the crimesHubApi is the thing that triggers it), but this might lead to only stale data being able to be read.

I won't neither confirm nor deny, because I didn't work with that or looked at that code, but that makes sense to me. 
To me, it wouldn't make sense to generate crimes for someone who didn't log in on the day and store all of that information into db (e.g. new cracking targets or pickpocketing targets, etc). 

I think crime specific statistics (statistics you can see for each crime) would be more realistic to get API for, but I don't know if you would make any use of that? 

Oh, certainly you could use that!

The only API-way of getting (most of) this data currently is by parsing all logs since migration. Obviously you can use fewer calls then :D

This would also allow for a more robust unique tracking, as long as the "considered unique" and "seen" outcome IDs are tracked. (because some unique outcomes have been changed over time, and this has made the tracking more challenging) (Edit: there was a dude that got a unique during a period where no logs were saved, so this is also a thing that would fix this)

The torn.report item view would also be just 1 / "# of crimes" calls after that, because it is visible in those statistics.

This would still be tied to a lot of changes, every time some change is made. For example a new forgery option.

Obviously, I would like both of those, the statistics and the real time data. :p

I personally wouldn't have an issue if self-regenerating targets like pickpocketing, cracking, disposal, etc. would only be reflected once a user triggered a calculation, but having more basic data of forgery cooldown timestamps, burglary target timestamps, hustling game skills, etc. should still be feasible...   

New Feature Request Events

Torns Calendar is a static list of events every year.
Having an endpoint would make it a little easier to automatically implement events via tools instead of manually grabbing each event at the start of each year. Consider a new endpoint torn -> events

Looking something like this
events: [
{
"event_name": [

{
"start_time": 1714316465,
"end_time": 1715316465,
"event_details": "Details of event",
"user_start_times": True/False
}

]
}

]

Suggestion type:
 - New feature request

What needs to be done:
 - add API to get racing data
 - this could potentially go under https://api.torn.com/torn/?selections=races and take the race ID(s) as parameter(s), or under User section       and have all your races 

Why do you need this:
For custom racing series and results it would be a lot easier and quicker to get race results. There are many big racing series (URT, TRL, etc) and many faction races that would benefit from this


Consider any drawbacks of your suggestion: 
 - This might have to change as other developers might want other info available as well

Example:

{
    "races": [

    {
        "race_id": number,
        "track_id": number,
        "race_name": string,
        "timestamp": number,
        "results": [
        {   
           "pos": number,
           "player_id": number,
           "racing_skill": number,
           "total_time": time/string,
           "best_lap_time": time/string,
           "car_id": number,
        },
        ...

    },

    ...

    ]
}

Someone else will probably expand on this idea and add to the example 

Suggestion type:

 - New feature request?

What needs to be done:

Bring back the inventory API

Why do you need this:

Various reasons. I would personally use it to remind myself of items I'm missing (temps / drugs / boosters / etc) or choose travel destination. Though I know a lot of other users have other uses in mind.

Consider any drawbacks of your suggestion: 

Aside from the server usage I'm not sure what drawbacks could be there. This was part of the API until very recently.

Example:

Could look exactly like the previous inventory API. Additionally it could accept filter of item id types or category ids.

Suggestion type:
 - Minor improvement

What needs to be done:

Currently 'signup' within the 'user > profile' endpoint is a string formatted as "yyyy-MM-dd HH:mm:ss". Doing this as epoch timestamp would be more uniform and easier to work with.

Why do you need this:

Exposing dates as epoch timestamp makes much more sense than a (formatted) string.

Consider any drawbacks of your suggestion:

No concerns for this improvement.

Suggestion Type: New Feature Request

I would love to see reverse name searches in the API

Why do we need this?

As the API stands, there is really no way to take a name (of a user, of a faction, etc), and get the associated ID. We (developers) can maintain lookup tables of names to IDs, but its quite challenging to keep up to date, since names can change at any time, and (excluding filters of active users) there are a TON of users to keep track of.

What needs to be done?

It would be great to have a new endpoint specifically for reverse name lookups. I.E. names->(player, faction, company) which would accept a name as the ID. For example, https://api.torn.com/name/lazerpent?selections=player&key= would return my ID and name (name so that capitalization can be captured).

It would also be great to be able to do partial matches (as search at the top of the page does, typing lazer shows 10 people whos name starts with lazer).

Drawbacks?

There are no drawbacks I can see. This functionality already exists exactly as written (in the search, which allows for all 3 types).

Suggestion Type: New Feature Request

New api endpoints to return paginated list of all users and factions in the game.

Why do we need this?

The above post reminded me of this: there's no way to get a list all users or factions in the game from the api without performing what is essentially an enumeration attack on the game to iterate through all the possible ids.

What needs to be done?

Using v1 as an example, something like https://api.torn.com/torn/?selections=users&key={key}&page={number} which returns a response along the lines of:

{
    "max_page": number,
    "users": [
        {
            "id": number,
            "name": string,
            "signup": timestamp,
            "level": number,
            "faction_id": number|null,
            "faction_name": string|null,
            "last_action": {
                "status": string,
                "timestamp": number
            },
            "status": {
                "description": string,
                "details": string,
                "state": string,
                "until": number
            }
        },

        // ... (100 or something results per page)
    ]
}

Similarly for factions https://api.torn.com/torn/?selections=factions&key={key}&page={number} and:

{
    "max_page": number,
    "factions": [
        {
            "id": number,
            "name": string,
            "tag": string,
            "age": number,
            "leader_id": number,
            "leader_name": string,
            "coleader_id": number|null,
            "coleader_name": string|null,
            "members": number,
            "capacity": number,
            "best_chain": best_chain,
            "respect": number,
            "rank": {
                "level": number,
                "name": string,
                "division": number,
                "position": number,
                "wins": number
            }
        },

        // ... (100 or something results per page)
    ]
}

Obviously the exact data returned probably needs a bit more thought put into it but this should be good enough for an example.

Drawbacks?

Shouldn't be anything major with the minimal concept. It's something which is already possible, just in a rather ugly manner. If there were more complex filtering options, especially for users, that might present an advantage to scripters depending on what those filtering options were (e.g. for finding chain targets).

That's a tough one. Something like 90% of all users and factions are basically inactive, so just returning a list would not be very useful. On the other hand, if it returned too much info about a player, it would be abused like hell. For example, if it gave last online status and company employment info, it would be abused like crazy by recruiters. Same goes for factions. This would even further remove player involvement imo. 

If you need a full list of factions (which you can use to filter out most active players anyway), you can use the one i have on chedslist About page.

An endpoint to get just the ids of active players would be great. R+