TurboVault API Documentation

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

Quick Start

  1. <%= link_to "Generate an API token", settings_api_tokens_path, class: "underline hover:text-indigo-600" %> 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

<%= link_to "Generate a token", settings_api_tokens_path, class: "text-indigo-600 hover:text-indigo-800" %> 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: