API Documentation

Complete reference for FFScouter's API endpoints

API Usage

Get Player Stats Endpoint

Endpoint

GET /api/v1/get-stats

Required Parameters

Parameter	Type	Description	Example
key	string	Your API key (16 alphanumeric characters)	abc123def456ghi
targets	string	Comma-separated list of player IDs to fetch	26755763,14263181

Rate Limiting

20 requests per minute per IP address

Example Request

curl -X GET "https://ffscouter.com/api/v1/get-stats?key=abc123def456ghi&targets=2675763,1426381"

Example Response

[
  {
    "player_id": 267456763,
    "fair_fight": 5.39,
    "bs_estimate": 2989885521,
    "bs_estimate_human": "2.99b",
    "last_updated": 1747333361
  },
  {
    "player_id": 142625381,
    "fair_fight": null,
    "bs_estimate": null,
    "bs_estimate_human": null,
    "last_updated": null
  }
]

Error Responses

Missing API Key

{
  "code": 1,
  "error": "API key is required"
}

Invalid API Key Format

{
  "code": 2,
  "error": "Invalid API key format. Key must be 16 alphanumeric characters"
}

Missing Targets

{
  "code": 3,
  "error": "The targets parameter is required"
}

Invalid Number of Targets

{
  "code": 4,
  "error": "At least one target ID is required and no more than 205"
}

Invalid Target IDs

{
  "code": 5,
  "error": "All target IDs must be positive integers"
}

Invalid API Key

{
  "code": 6,
  "error": "Invalid API key. Please sign up at ffscouter.com to use this service"
}

Error Codes Reference

Code	Description	HTTP Status
1	API key is required	400
2	Invalid API key format. Key must be 16 alphanumeric characters	400
3	The targets parameter is required	400
4	At least one target ID is required and no more than 205	400
5	All target IDs must be positive integers	400
6	Invalid API key. Please sign up at ffscouter.com to use this service	401

Notes

All player IDs must be valid Torn player IDs
The API key must be active and have the necessary permissions
Some data may be cached for up to 5 minutes to improve performance
Up to 205 player IDs can be requested per request

Check Key Endpoint

Check API Key Status Endpoint

Endpoint

GET /api/v1/check-key

Required Parameters

Parameter	Type	Description	Example
key	string	Your API key (16 alphanumeric characters)	abc123def456ghi

Rate Limiting

10 requests per minute per IP address

Example Request

curl -X GET "https://ffscouter.com/api/v1/check-key?key=abc123def456ghi"

Example Response

{
  "key": "abc123def456ghi",
  "is_registered": true,
  "registered_at": 1640995200,
  "last_used": 1747333361
}

Response Fields

Field	Type	Description
key	string	The API key that was provided in the request
is_registered	boolean	Whether the API key is registered in the system
registered_at	integer\|null	Unix timestamp of when the key was registered (null if not registered)
last_used	integer\|null	Unix timestamp of last successful usage for battle stat predictions (null if never used)

Error Responses

Missing API Key

{
  "code": 1,
  "error": "API key is required"
}

Invalid API Key Format

{
  "code": 2,
  "error": "Invalid API key format. Key must be 16 alphanumeric characters"
}

Error Codes Reference

Code	Description	HTTP Status
1	API key is required	400
2	Invalid API key format. Key must be 16 alphanumeric characters	400

Notes

This endpoint checks if an API key is registered with FFScouter
The last_used timestamp is updated whenever the key is successfully used in get-stats or get-targets endpoints
registered_at shows when the API key was first added to the system
All timestamps are Unix timestamps (seconds since epoch)
This endpoint does not consume API usage or make external requests
Using this endpoint does not register an API key to FFScouter

Find Targets Endpoint

Get Target Players Endpoint

Endpoint

GET /api/v1/get-targets

Required Parameters

Parameter	Type	Description	Example
key	string	Your API key (16 alphanumeric characters)	abc123def456ghi

Optional Parameters

Parameter	Type	Default	Description
preset	string	null	Preset mode for quick filtering ("respect", "level")
minlevel	integer	1	Minimum player level (inclusive). If provided without maxlevel, filters level >= minlevel (1-100)
maxlevel	integer	100	Maximum player level (inclusive). If provided without minlevel, filters level <= maxlevel (1-100)
inactiveonly	integer	1	Filter for inactive players only (14+ days since last action) (0 or 1)
minff	float	1.00	Minimum fair fight value (inclusive). If provided without maxff, filters FF >= minff (≥1.0)
maxff	float	3.00	Maximum fair fight value (inclusive). If provided without minff, filters FF <= maxff (≥1.0)
limit	integer	20	Maximum number of targets to return (1-50)
factionless	integer	0	Filter for factionless players only (0 or 1)

Preset Modes

Respect Preset

Optimized for gaining maximum respect per attack. When using this preset:

Only "key" and "limit" parameters are allowed
Automatically filters for fair fight range 2.00-3.00
Shows only inactive players (14+ days since last action)
Results ordered by battle stat score (descending)

Level Preset

Optimized for level-based targeting. When using this preset:

Only "key" and "limit" parameters are allowed
Automatically filters for fair fight ≤ 3.00
No minimum fair fight restriction
Results ordered by level (descending)

Rate Limiting

5 requests per minute per IP address

Example Requests

Basic Request (Randomized Results)

curl -X GET "https://ffscouter.com/api/v1/get-targets?key=abc123def456ghi"

Respect Preset

curl -X GET "https://ffscouter.com/api/v1/get-targets?key=abc123def456ghi&preset=respect"

Level Preset

curl -X GET "https://ffscouter.com/api/v1/get-targets?key=abc123def456ghi&preset=level"

Custom Filter

curl -X GET "https://ffscouter.com/api/v1/get-targets?key=abc123def456ghi&minlevel=20&maxlevel=50&minff=1.5&maxff=2.5&inactiveonly=1&limit=25"

Factionless Players Only

curl -X GET "https://ffscouter.com/api/v1/get-targets?key=abc123def456ghi&factionless=1"

Example Response

{
  "parameters": {
    "key": "abc123def456ghi",
    "preset": null,
    "minlevel": 1,
    "maxlevel": 100,
    "inactiveonly": 1,
    "minff": 1.00,
    "maxff": 3.00,
    "limit": 20,
    "factionless": 0,
    "generated_at": 1640995200
  },
  "targets": [
    {
      "player_id": 12345,
      "name": "PlayerName",
      "level": 25,
      "fair_fight": 1.8,
      "bss_public": 50000,
      "bss_public_timestamp": 1640995000,
      "bs_estimate": 6750000,
      "bs_estimate_human": "6.75m",
      "last_action": 1640994000
    },
    {
      "player_id": 67890,
      "name": "AnotherPlayer",
      "level": 42,
      "fair_fight": 2.1,
      "bss_public": 75000,
      "bss_public_timestamp": 1640994800,
      "bs_estimate": 10125000,
      "bs_estimate_human": "10.13m",
      "last_action": 1640993000
    }
  ]
}

Error Responses

No Targets Found

{
  "code": 17,
  "error": "No targets found matching the specified criteria"
}

Invalid Preset with Extra Parameters

{
  "code": 15,
  "error": "When preset is specified, only \"key\" and \"limit\" parameters are allowed"
}

Invalid Level Range

{
  "code": 10,
  "error": "minlevel cannot be greater than maxlevel"
}

Invalid Limit Range

{
  "code": 16,
  "error": "limit must be an integer between 1 and 50"
}

Error Codes Reference

Code	Description	HTTP Status
1	API key is required	400
2	Invalid API key format. Key must be 16 alphanumeric characters	400
6	Invalid API key. Please sign up at ffscouter.com to use this service	401
7	Invalid preset value. Must be "respect" or "level"	400
8	minlevel must be an integer between 1 and 100	400
9	maxlevel must be an integer between 1 and 100	400
10	minlevel cannot be greater than maxlevel	400
11	inactiveonly must be 0 or 1	400
12	minff must be a number greater than or equal to 1	400
13	maxff must be a number greater than or equal to 1	400
14	minff cannot be greater than maxff	400
15	When preset is specified, only "key" and "limit" parameters are allowed	400
16	limit must be an integer between 1 and 50	400
17	No targets found matching the specified criteria	404
18	factionless must be 0 or 1	400

Notes

Default queries return randomized results for variety
Custom queries return results ordered by battle stat score (descending)
Inactive players are those with no activity for 14+ days
Fair fight values are calculated based on your private battle stat score
Some data may be cached for up to 5 minutes to improve performance
Up to 50 targets can be requested per request
last_action is a Unix timestamp of the player's last activity