API Documentation

Use the Final Parsec API for programmatic access to our various features.

Authentication

Include the API token for your user account in the authorization header when making requests. You can find this token in the "API Token" section of the Edit user account page.

Here's how to add the token to the request header using cURL:

Example request with bearer token

curl https://www.finalparsec.com/api/games \
  -H "Authorization: Token token={token}"

Tokens allow for actions to be performed on your behalf. Keep them private and do not publish them publicly.

You can regenerate your token if you suspect it has been compromised.

Only one token for your account is valid at a time.

Games

This represents a game hosted on Final Parsec.

The Game object

  • Name
    id
    Type
    integer
    Description

    Unique identifier for the game.

  • Name
    name
    Type
    string
    Description

    The game's name, meant to be displayed to the player.

  • Name
    assets
    Type
    array
    Description

    The assets required to make the game playable. Typically includes wasm, pck, js, and similar files. Assets have a filename and base64 encoded content.

Create a game

POST /api/games

This endpoint allows you to create new games. A name is required.

An "anonymous game" will be created if an authentication token is not provided with the request. Anonymous games are shown without any association to a user profile. ANY user may claim anonymous games as their own or transfer the game assets to a game they own.

Request - just a game with a name

curl -X POST https://www.finalparsec.com/api/games \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{ "game": { "name": "Hello World" } }'

Optionally, a collection of assets can be included to make your game immediately playable.

See the Final-Parsec/publish-game GitHub Action if you are interested in performing this step as part of a workflow.

Request with chonky json payload in distinct file

curl -X POST https://www.finalparsec.com/api/games \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d @payload.json

payload.json - bundle metadata and assets here before upload

{
  "game": {
    "name": "My Game",
    "assets": [
      {
        "filename": "my_game.pck",
        "data": "data:application/octet-stream;base64,{encoded_asset_data_here}"
      },
      {
        "filename": "my_game.wasm",
        "data": "data:application/octet-stream;base64,{encoded_asset_data_here}"
      }
    ]
  }
}

List your games

GET /api/games

This endpoint allows you to retrieve a list of games you have uploaded.

Game assets are not included in this response.

Request

curl https://www.finalparsec.com/api/games \
  -H "Authorization: Token token={token}"

Response

{
  "games": [
    {
      "id": 1,
      "name": "Aurora TD"
    },
    {
      "id": 11,
      "name": "Office Sim"
    }
  ]
}

Update a game

PATCH /api/games/{id}

This endpoint allows for partial updates of existing games.

Send a payload similar to creating a game, but include the unique ID for the game to update in the URL.

Attributes which are not included in the payload will remain unmodified.

Request - renaming a game

curl -X PATCH https://www.finalparsec.com/api/games/{id} \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{ "game": { "name": "Updated Game Name" } }'

Get a game

GET /api/games/{id}

This endpoint allows you to retrieve a single game.

Game assets are included in this response.

Request

curl https://www.finalparsec.com/api/games/{id} \
  -H "Authorization: Token token={token}"

Response

{
  "game": {
    "id": 1,
    "name": "Aurora TD",
    "assets": [
      {
        "filename": "my_game.pck",
        "data": "data:application/octet-stream;base64,{encoded_asset_data_here}"
      },
      {
        "filename": "my_game.wasm",
        "data": "data:application/octet-stream;base64,{encoded_asset_data_here}"
      }
    ]
  }
}

Art Maker

Generate animation and doodad sprite sheets programmatically with the same models and processes that support the Art Maker tool. Art generation is asynchronous. You submit a request and receive a request_id to poll until your image is ready.

Image generation counts toward your daily limit.

Generate art

POST /api/art_maker

Submit an art generation request. The same endpoint is used to poll for results by passing the request_id from a previous response.

  • Name
    mode
    Type
    string
    Description

    Required. "animation" to generate an animated sprite sheet, or "doodad" to generate static scene objects.

  • Name
    art_style
    Type
    string
    Description

    Required. One of: "Pixel Art", "Cartoon", "Vector Art", "Manga-Inspired", or "Custom". Matches the Style selector in the Art Maker tool.

  • Name
    custom_art_style
    Type
    string
    Description

    Required when art_style is "Custom". Describe the style freely, e.g. "8-bit NES" or "Cel Shaded toon".

  • Name
    perspective
    Type
    string
    Description

    Required. One of: "Top Down", "Isometric", or "Side View Scroller 2D". Matches the Perspective selector in the Art Maker tool.

  • Name
    animated_object
    Type
    string
    Description

    Required when mode is "animation". The character or object to animate, e.g. "knight" or "goblin". Matches the Animated Object field.

  • Name
    animated_action
    Type
    string
    Description

    Required when mode is "animation". The action to perform, e.g. "walking" or "casting a spell". Matches the Action field.

  • Name
    doodad_items
    Type
    string
    Description

    Required when mode is "doodad". The items to generate, e.g. "treasure chest, wooden table". Matches the Doodad Items field.

  • Name
    doodad_theme
    Type
    string
    Description

    Required when mode is "doodad". The visual theme, e.g. "high fantasy" or "steampunk". Matches the Theme field.

  • Name
    world_slug
    Type
    string
    Description

    Optional. Associate the generated image with a specific world by its slug. Defaults to your current world, or creates one if you have none.

  • Name
    request_id
    Type
    integer
    Description

    When polling: the request_id from a prior response. All other params are ignored when this is present.

On success, the initial request returns a request_id. Poll the same endpoint with that ID until status is "finished", at which point an image_url is included. We recommend a 30s polling interval; excessive polling may result in your requests being rate limited.

Possible status values: pending, in_progress, finished, failed, moderated.

Animation example

Step 1 — Submit the request

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "animation",
    "art_style": "Pixel Art",
    "perspective": "Top Down",
    "animated_object": "knight",
    "animated_action": "walking"
  }'

Response

{ "request_id": 42 }

Step 2 — Poll for the result

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": 42 }'

Response when finished

{
  "status": "finished",
  "image_url": "https://www.finalparsec.com/rails/active_storage/blobs/..."
}

Doodad example

Request

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "doodad",
    "art_style": "Pixel Art",
    "perspective": "Top Down",
    "doodad_items": "treasure chest, wooden table",
    "doodad_theme": "high fantasy"
  }'