Documentation

Asset API

Endpoints for managing assets in the Grids marketplace.

List Assets

GET /assets

Query parameters:

Param	Type	Description
`type`	`string`	Filter by asset type (`texture`, `audio`, `video`, `model`, `script`)
`search`	`string`	Search by name
`limit`	`number`	Max results (default: 50)
`offset`	`number`	Pagination offset

Response:

{
  "assets": [
    {
      "id": "abc123",
      "name": "Brick Wall",
      "type": "texture",
      "description": "Red brick wall texture",
      "thumbnail_url": "https://...",
      "creator_id": "user456",
      "creator_name": "BuilderPro",
      "downloads": 1234,
      "created_at": "2026-01-15T00:00:00Z"
    }
  ],
  "total": 128
}

Get Asset

GET /assets/:id

Returns full asset metadata including download info.

Upload Asset

POST /assets
Content-Type: multipart/form-data
Authorization: Bearer <token>

Form fields:

Field	Type	Required	Description
`file`	`File`	Yes	Asset file
`name`	`string`	Yes	Display name
`type`	`string`	Yes	Asset type
`description`	`string`	No	Description
`thumbnail`	`File`	No	Thumbnail image

Signed Download URL

POST /assets/:id/sign
Authorization: Bearer <token>

Returns an HMAC-signed URL and a per-stream descramble token. The token is valid for 1 hour and is required by the client to recover the original bytes.

Response:

{
  "url": "https://api.a-new-world.com/api/assets/abc123/stream?token=…&expires=1712000000",
  "expires": 1712000000,
  "token": "base64url-hmac-token",
  "scramble": "xor-v1"
}

Field	Type	Description
`url`	`string`	Fully qualified signed URL — pass directly to `GET`
`expires`	`number`	Unix epoch (seconds) when the signed URL becomes invalid
`token`	`string`	Per-stream token used as input to the XOR-v1 descramble
`scramble`	`string`	Scramble protocol identifier (currently always `xor-v1`)

Scrambled Stream

GET /assets/:id/stream?token=…&expires=…

Downloads the asset bytes with a continuous XOR scramble applied. The response includes the following headers:

Header	Description
`Content-Type`	Always `application/octet-stream` (opaque)
`X-Grids-Original-Type`	The asset's true MIME type (e.g. `image/png`)
`X-Grids-Scramble`	Protocol identifier (`xor-v1`)

XOR-v1 Descramble

The XOR key is the first 32 ASCII bytes of the token returned by /sign, right-padded with '0' (0x30) if the token is shorter than 32 bytes. The key is applied cyclically and continuously across the entire stream (the position counter persists across chunk boundaries, it does not reset per chunk):

key[i] = token_ascii[i]          for 0 <= i < min(len(token), 32)
key[i] = '0'                     for len(token) <= i < 32

for each byte b at stream offset i:
    plain[i] = b ^ key[i % 32]

This is the same operation that scrambled the bytes server-side — XOR is symmetric, so applying it again recovers the original file.