TurboVault API Documentation

RESTful API for accessing and managing your video game collection programmatically.

Quick Start

  1. Generate an API token in your settings
  2. Include the token in the Authorization header
  3. Make requests to https://yourdomain.com/api/v1/...

Table of Contents

Authentication

All API requests require authentication using a bearer token.

Authorization: Bearer YOUR_API_TOKEN_HERE

Generate a token in your settings page.

Security: Keep your API tokens secure. Do not share them or commit them to version control.

Games

List Games

GET /api/v1/games

Returns a paginated list of your games.

Query Parameters:

page Page number (default: 1)
per_page Items per page (default: 50, max: 100)
format Filter by format: physical or digital
platform_id Filter by platform ID
genre_id Filter by genre ID

Example Request:

curl -X GET "https://yourdomain.com/api/v1/games?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
  "games": [
    {
      "id": 1,
      "title": "The Legend of Zelda: Ocarina of Time",
      "platform": "Nintendo 64",
      "format": "physical",
      "date_added": "2024-01-15",
      "completion_status": "completed",
      "user_rating": 5,
      "igdb_id": 1234,
      "condition": "very_good",
      "price_paid": "45.99",
      "location": "Bedroom Shelf A",
      "genres": ["Action", "Adventure"],
      "collections": ["Favorites", "N64 Collection"]
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 3,
    "total_count": 25
  }
}

Get a Game

GET /api/v1/games/:id

Returns details for a specific game.

Example Request:

curl -X GET "https://yourdomain.com/api/v1/games/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a Game

POST /api/v1/games

Add a new game to your collection.

Request Body:

{
  "game": {
    "title": "Super Mario 64",
    "platform_id": 4,
    "format": "physical",
    "date_added": "2024-03-28",
    "completion_status": "backlog",
    "user_rating": null,
    "condition": "good",
    "price_paid": "35.00",
    "location": "Living Room Shelf",
    "genre_ids": [1, 3],
    "collection_ids": [2]
  }
}

Update a Game

PUT/PATCH /api/v1/games/:id

Update an existing game's information.

Delete a Game

DELETE /api/v1/games/:id

Permanently delete a game from your collection.

Collections

List Collections

GET /api/v1/collections

Get a Collection

GET /api/v1/collections/:id

Includes all games in the collection.

Create a Collection

POST /api/v1/collections

Update a Collection

PUT/PATCH /api/v1/collections/:id

Delete a Collection

DELETE /api/v1/collections/:id

Games in the collection will not be deleted.

Platforms

List Platforms

GET /api/v1/platforms

Returns all available gaming platforms.

Get a Platform

GET /api/v1/platforms/:id

Genres

List Genres

GET /api/v1/genres

Returns all available game genres.

Get a Genre

GET /api/v1/genres/:id

Error Handling

The API uses standard HTTP response codes:

Code Meaning
200 Success
201 Created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing token
404 Not Found
422 Unprocessable Entity - Validation errors
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format:

{
  "error": "Validation failed",
  "details": {
    "title": ["can't be blank"],
    "platform_id": ["must exist"]
  }
}

Rate Limits

API requests are currently not rate-limited, but this may change in the future. Please be respectful and avoid excessive requests.

Best Practice: Cache responses when possible and implement exponential backoff for failed requests.

Need Help?

If you have questions or encounter issues with the API:

  • Check the API tokens page for troubleshooting
  • Review this documentation for endpoint details
  • Contact support if you need assistance