Game Assets

Manage worlds, avatars, and props with versioning

The Game Assets API manages user-created content like worlds, avatars, and props with version control and branching support.

Asset Types

Type	Description
`world`	Virtual environments/maps
`avatar`	Player character models
`prop`	In-world objects and items

Visibility

Visibility	Description
`public`	Anyone can view and branch
`private`	Only owner can access

Create Asset

Create a new game asset.

POST /v1/game/assets
Authorization: Bearer {token}

{
  "name": "My First World",
  "type": "world",
  "visibility": "private"
}

Response (201 Created):

{
  "id": "123456789",
  "owner_id": "12345",
  "type": "world",
  "name": "My First World",
  "visibility": "private",
  "current_version": 0,
  "created_at": 1703520000,
  "updated_at": 1703520000
}

Error Codes:

Code	Description
`ASSET_NAME_REQUIRED`	Name cannot be empty
`ASSET_NAME_TOO_LONG`	Max 255 characters
`INVALID_ASSET_TYPE`	Must be: world, avatar, prop
`INVALID_VISIBILITY`	Must be: public, private
`DUPLICATE_ASSET_NAME`	Name already exists

List Assets

List your assets with filtering.

GET /v1/game/assets?type=world&limit=50&cursor={cursor}
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
`type`	-	Filter by asset type
`limit`	50	Max results (1-100)
`cursor`	-	Pagination cursor

Response:

{
  "assets": [
    {
      "id": "123456789",
      "owner_id": "12345",
      "type": "world",
      "name": "My First World",
      "visibility": "private",
      "current_version": 3,
      "created_at": 1703520000,
      "updated_at": 1703525000
    }
  ],
  "next_cursor": "eyJvIjoxMH0="
}

Get Asset

Get asset details with recent versions.

GET /v1/game/assets/{assetID}
Authorization: Bearer {token}

Response:

{
  "id": "123456789",
  "owner_id": "12345",
  "type": "world",
  "name": "My First World",
  "visibility": "private",
  "current_version": 3,
  "created_at": 1703520000,
  "updated_at": 1703525000,
  "versions": [
    {
      "id": "999888777",
      "asset_id": "123456789",
      "version": 3,
      "size_bytes": 5242880,
      "created_at": 1703525000
    },
    {
      "id": "888777666",
      "asset_id": "123456789",
      "version": 2,
      "size_bytes": 4194304,
      "created_at": 1703522000
    }
  ]
}

Update Asset

Update asset metadata.

PUT /v1/game/assets/{assetID}
Authorization: Bearer {token}

{
  "name": "Renamed World",
  "visibility": "public"
}

Response:

{
  "id": "123456789",
  "owner_id": "12345",
  "type": "world",
  "name": "Renamed World",
  "visibility": "public",
  "current_version": 3,
  "created_at": 1703520000,
  "updated_at": 1703530000
}

Delete Asset

Soft delete an asset.

DELETE /v1/game/assets/{assetID}
Authorization: Bearer {token}

Response: 204 No Content

Branch Asset

Create a new asset by branching from an existing one. This copies the content from a specific version.

POST /v1/game/assets/{assetID}/branch
Authorization: Bearer {token}

{
  "name": "My Forked World",
  "from_version": 2
}

Notes:

from_version is optional; defaults to latest version
Can branch from public assets you don't own
Creates a new asset with version 1

Response (201 Created):

{
  "asset": {
    "id": "234567890",
    "owner_id": "12345",
    "type": "world",
    "name": "My Forked World",
    "visibility": "private",
    "current_version": 1,
    "created_at": 1703530000,
    "updated_at": 1703530000
  },
  "version": {
    "id": "111222333",
    "asset_id": "234567890",
    "version": 1,
    "size_bytes": 4194304,
    "created_at": 1703530000,
    "branched_from_asset_id": "123456789",
    "branched_from_version": 2
  }
}

Error Codes:

Code	Description
`ASSET_NOT_FOUND`	Source asset not found
`VERSION_NOT_FOUND`	Specified version not found
`NO_VERSIONS_TO_BRANCH`	Source has no versions

List Versions

List all versions of an asset.

GET /v1/game/assets/{assetID}/versions?limit=50&cursor={cursor}
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
`limit`	50	Max results (1-100)
`cursor`	-	Pagination cursor

Response:

{
  "versions": [
    {
      "id": "999888777",
      "asset_id": "123456789",
      "version": 3,
      "size_bytes": 5242880,
      "created_at": 1703525000
    }
  ],
  "next_cursor": null
}

Get Version

Get details of a specific version.

GET /v1/game/assets/{assetID}/versions/{version}
Authorization: Bearer {token}

Response:

{
  "id": "999888777",
  "asset_id": "123456789",
  "version": 3,
  "size_bytes": 5242880,
  "created_at": 1703525000,
  "branched_from_asset_id": null,
  "branched_from_version": null
}

Get Public Asset

Get a public asset with its latest version (any authenticated user).

GET /v1/game/public/{type}/{assetID}
Authorization: Bearer {token}

Response:

{
  "id": "123456789",
  "owner_id": "67890",
  "type": "world",
  "name": "Community World",
  "visibility": "public",
  "current_version": 5,
  "created_at": 1703500000,
  "updated_at": 1703530000,
  "versions": [
    {
      "id": "999888777",
      "asset_id": "123456789",
      "version": 5,
      "size_bytes": 10485760,
      "created_at": 1703530000
    }
  ]
}

Uploading Asset Content

Asset content is uploaded via the Uploads API. To upload a new version:

Start an upload with upload_type: "game_asset"
Include asset_id to add a new version to existing asset
Or include asset_type to create a new asset
Upload the file to the presigned URL
Complete the upload

See Uploads API for details.