REST API

TinyEmulator backend (retro-server) provides a REST API for game management, cloud saves, and netplay.

Overview

The REST API is available when you self-host the TinyEmulator backend. The API provides endpoints for:

• Game metadata and listings
• Cloud save storage
• User favorites
• Netplay room management
• Cheat code lookup

info

To use the REST API, you need to self-host the TinyEmulator backend server.

Authentication

Protected endpoints require JWT Bearer token authentication:

Authorization: Bearer <your_jwt_token>

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "username": "your_username",
    "avatar": "https://..."
  }
}

Game Endpoints

Get Home Feed

GET /api/v1/home

Returns featured games, banners, and categories.

Get Game by UUID

GET /api/v1/game/:uuid

Cloud Save Endpoints

Upload Save

POST /api/v1/cloudsave/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <save_file>
slot: 0
game_id: <game_uuid>

List Saves

GET /api/v1/cloudsave/list?game_id=<game_uuid>
Authorization: Bearer <token>

Download Save

GET /api/v1/cloudsave/download?game_id=<game_uuid>&slot=0
Authorization: Bearer <token>

Favorites Endpoints

Get Favorites

GET /api/v1/me/favorites
Authorization: Bearer <token>

Add Favorite

POST /api/v1/me/favorites
Authorization: Bearer <token>
Content-Type: application/json

{
  "game_id": "<game_uuid>"
}

Remove Favorite

DELETE /api/v1/me/favorites/:game_id
Authorization: Bearer <token>

Cheats Endpoints

Search by CRC32

GET /api/v1/cheats/crc/:crc

Search by Game Name

GET /api/v1/cheats/name/:name

Get Cheats by System

GET /api/v1/cheats/system/:system

Systems: nes, snes, gba, genesis, arcade

Room Endpoints

Search Rooms

GET /api/v1/rooms?keyword=&core=&page=1&pagesize=20

Create Room

POST /api/v1/rooms
Authorization: Bearer <token>
Content-Type: application/json

{
  "core": "nes",
  "game": "Super Mario Bros",
  "password": ""
}

Short Link Endpoint

Create Short Link

POST /api/v1/short
Content-Type: application/json

{
  "url": "https://play.tinyemulator.com?core=nes&rom=game.nes"
}

Response:

{
  "code": "abc123"
}

Error Responses

All endpoints return standard HTTP status codes:

Status	Description
200	Success
201	Created
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
500	Server error

Error response body:

{
  "error": "Error message here"
}