Get Started

API Endpoint

https://tsto.app/

The Project Springfield API is a standardized backend interface designed for all developers building or maintaining Project Springfield servers and services.

This API enables seamless access to common backend features such as user authentication, content handling, and secure interactions.

To use the API, you must obtain an API key. Please log in and view your key on the account page or contact us for help.

Account Wipe Notice

Description: Sends a standalone account wipe confirmation email for external server developers.

Endpoint: Exclusive POST /api/account/wipeNotice

Query Parameters
Field Type Description Example
emailAddress String User email address [email protected]
wipedBy String Name of the person or system that performed the wipe Project Springfield Admin
source String External system or server that triggered the wipe notice My TSTO Private Server
deletedItems Array/String Optional extra deleted items. Can be a JSON array or comma-separated string. ["Town save data", "Inventory data", "Login tokens"]
Example CURL Request: 
curl \
-X POST https://tsto.app/api/account/wipeNotice \
-G
--data-urlencode "[email protected]"
--data-urlencode "wipedBy=Project Springfield Admin"
--data-urlencode "source=My TSTO Private Server"
--data-urlencode "deletedItems=["Town save data", "Inventory data", "Login tokens"]"
Example Response: 
{
  "success": true,
  "message": "Account wipe notice queued",
  "target": "email"
}

Generate Auth Code

Description: Generate and send an authentication code without returning the code in the response

Endpoint: Exclusive POST /api/auth/generateCode

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
email String User email address [email protected]
username String Username Ethan
teamName String Team Name Project Springfield
Example CURL Request: 
curl \
-X POST https://tsto.app/api/auth/generateCode \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "[email protected]"
--data-urlencode "username=Ethan"
--data-urlencode "teamName=Project Springfield"
Example Response: 
{
  "status": 200,
  "generated": true,
  "active": true,
  "message": "Authentication code generated",
  "target": "email",
  "lasts": 5
}

Test API Key Validity

Description: Check the validity of your API key. This endpoint is used to verify that the API key is valid and can be used for further requests.

Endpoint: Exclusive GET /api/handshake

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
Example CURL Request: 
curl \
-X GET https://tsto.app/api/handshake \
-G
--data-urlencode "apikey=<YOUR KEY>"
Example Response: 
{
  "valid": true
}

Quotes by Character

Description: Get all quotes from a specific character

Endpoint: GET /api/quotes/character/:name

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
page Number Page to look up 1
amount Number Amount per page 50
Example CURL Request: 
curl \
-X GET https://tsto.app/api/quotes/character/homer%20simpson \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "page=1"
--data-urlencode "amount=50"
Example Response: 
{
  "page": 1,
  "amount": 50,
  "total": 27909,
  "results": [
    {
      "id": 48071,
      "episode_id": 57934,
      "line_number": 205,
      "quote": "Now, here's my \"Everything's Okay\" Alarm.",
      "character": "Homer Simpson",
      "location": "Simpson Home",
      "word_count": 6
    },
    {
      "id": 45385,
      "episode_id": 55239,
      "line_number": 196,
      "quote": "\"Da, da, da, dada, dada, da, da. Da, da, da, dada, dada, da, da. Da, da, da, dada, dada, da, da.\" \"After the beep.\"",
      "character": "Homer Simpson",
      "location": "Simpson Home",
      "word_count": 24
    }
  ]
}

Quotes by Location

Description: Get all quotes spoken at a specific location

Endpoint: GET /api/quotes/location/:location

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
page Number Page to look up 1
amount Number Amount per page 50
Example CURL Request: 
curl \
-X GET https://tsto.app/api/quotes/location/Homer's%20Car \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "page=1"
--data-urlencode "amount=50"
Example Response: 
{
  "page": 1,
  "amount": 50,
  "total": 442,
  "results": [
    {
      "id": 50431,
      "episode_id": 60295,
      "line_number": 213,
      "quote": "I don't think so.",
      "character": "Homer Simpson",
      "location": "Homer's Car",
      "word_count": 4
    },
    {
      "id": 95259,
      "episode_id": 105324,
      "line_number": 367,
      "quote": "At least you have something you're good at. I'm thirty-eight years old, drivin' a crappy car, with a son who doesn't respect me, and I'm one Snickers pie away from losing my foot to diabetes. Mmm, Snickers pie.",
      "character": "Homer Simpson",
      "location": "Homer's Car",
      "word_count": 38
    }
  ]
}

Random Quote

Description: Get a random line from a random episode

Endpoint: GET /api/randomQuote

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
Example CURL Request: 
curl \
-X GET https://tsto.app/api/randomQuote \
-G
--data-urlencode "apikey=<YOUR KEY>"
Example Response: 
{
  "id": 17063,
  "episode_id": 26726,
  "line_number": 90,
  "quote": "No, Homer. Let's do it. Let's call room service!",
  "character": "Mindy",
  "location": "Homer's Hotel Room",
  "word_count": 9
}

Search Quotes

Description: Search for quotes by keyword

Endpoint: GET /api/quotes/search

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
q String Quote to search Suspect is hatless
Example CURL Request: 
curl \
-X GET https://tsto.app/api/quotes/search \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "q=Suspect is hatless"
Example Response: 
{
  "count": 59,
  "results": [
    {
      "id": 1133,
      "episode_id": 10684,
      "line_number": 36,
      "quote": "Hey Homer, we saved you a doughnut.",
      "character": "Lenny Leonard",
      "location": "Springfield Nuclear Power Plant",
      "word_count": 7
    },
    {
      "id": 1849,
      "episode_id": 11393,
      "line_number": 38,
      "quote": "Hey Homer, how's your neighbor's store doing?",
      "character": "Barney Gumble",
      "location": "Moe's Tavern",
      "word_count": 7
    }
  ]
}

Send Auth Code

Description: Send an authentication code to a user's email

Endpoint: Exclusive POST /api/auth/sendCode

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
emailAddress String User's email address [email protected]
teamName String Name of the team sending this email Project Springfield
username String Their username ethanprimmer
Example CURL Request: 
curl \
-X POST https://tsto.app/api/auth/sendCode \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "[email protected]"
--data-urlencode "teamName=Project Springfield"
--data-urlencode "username=ethanprimmer"
Example Response: 
{
  "status": 200,
  "message": "Authentication code sent successfully",
  "target": "email",
  "code": "12345"
}

List Sprites

Description: List folders/files under Sprites/. Uses S3 ListObjectsV2 with Delimiter=/

Endpoint: GET /api/sprites

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
path String Relative folder inside Sprites/ simpsonshouse
pageSize Number Max items (<=1000) 100
token String Continuation token xyz
Example CURL Request: 
curl \
-X GET https://tsto.app/api/sprites \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "path=simpsonshouse"
--data-urlencode "pageSize=100"
--data-urlencode "token=xyz"
Example Response: 
{
  "base": "/sprites",
  "root": "Sprites",
  "cwd": "simpsonshouse",
  "parent": "",
  "items": [
    {
      "type": "dir",
      "name": "interior",
      "path": "simpsonshouse/interior"
    },
    {
      "type": "file",
      "name": "house.png",
      "path": "simpsonshouse/house.png",
      "size": 12345,
      "lastModified": "2025-08-16T01:23:45.000Z",
      "url": "/sprites/raw?path=simpsonshouse/house.png"
    }
  ],
  "nextToken": null
}

Get Sprite File

Description: Returns a short-lived signed URL to download the asset (or 302 if redirect=1).

Endpoint: GET /api/sprites/raw

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
path String Relative file inside Sprites/ simpsonshouse/Neutral/0.png
download String Force download (1/0) 1
redirect String 302 redirect to signed URL (1/0) 1
Example CURL Request: 
curl \
-X GET https://tsto.app/api/sprites/raw \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "path=simpsonshouse/Neutral/0.png"
--data-urlencode "download=1"
--data-urlencode "redirect=1"
Example Response:
Example Image

Upload Rejection Email

Description: Sends an email or Discord alert when a town upload is rejected

Endpoint: Exclusive POST /api/town/uploadReject

Query Parameters
Field Type Description Example
emailAddress String User email [email protected]
username String Their username homer
town String Town name Springfield Heights
description String Optional reason Incompatible layout or corrupted file
Example CURL Request: 
curl \
-X POST https://tsto.app/api/town/uploadReject \
-G
--data-urlencode "[email protected]"
--data-urlencode "username=homer"
--data-urlencode "town=Springfield Heights"
--data-urlencode "description=Incompatible layout or corrupted file"
Example Response: 
{
  "message": "Email sent"
}

Upload Success Email

Description: Sends an email alert when a town upload is successful

Endpoint: Exclusive POST /api/town/uploadSuccess

Query Parameters
Field Type Description Example
emailAddress String User email [email protected]
username String Their username homer
town String Town name Springfield Heights
description String Optional description New heights expansion added.
Example CURL Request: 
curl \
-X POST https://tsto.app/api/town/uploadSuccess \
-G
--data-urlencode "[email protected]"
--data-urlencode "username=homer"
--data-urlencode "town=Springfield Heights"
--data-urlencode "description=New heights expansion added."
Example Response: 
{
  "message": "Email sent"
}

Validate Auth Code

Description: Validate an authentication code for a user email

Endpoint: Exclusive POST /api/auth/validateCode

Query Parameters
Field Type Description Example
apikey String Your API key YOUR KEY
email String User email address [email protected]
code String Authentication code supplied by the user 12345
Example CURL Request: 
curl \
-X POST https://tsto.app/api/auth/validateCode \
-G
--data-urlencode "apikey=<YOUR KEY>"
--data-urlencode "[email protected]"
--data-urlencode "code=12345"
Example Response: 
{
  "status": 200,
  "valid": true,
  "active": false,
  "message": "Authentication code validated"
}