VoxBox API

Programmatic access to the VoxBox platform.

Base URL: https://voxbox.store

Authentication

POST /api/auth/sign-in

Request

{
  "username": "your_username_or_email",
  "password": "your_password"
}

Response

{
  "accessToken": "your_access_jwt",
  "refreshToken": "your_refresh_jwt"
}

Note: Only the refresh token is used for authenticated requests.

Models

POST /api/model/upload

Upload a new model (requires authentication).

Headers

Header	Value	Required	Details
Cookie	jwt=refresh jwt	Yes	Refresh JWT used for authentication
Content-Type	multipart/form-data	Yes	Required for file upload requests

Body

Field	Type	Required	Details
name	string	Yes	2–64 characters
description	string	Yes	Max 512 characters
category	enum	Yes	Character, Environment, Prop, Vegetation, Vehicle, Random, Weapon, Architecture
license	enum	Yes	CC-0, CC-BY, CC-BY-SA, CC-BY-ND, CC-BY-NC, CC-BY-NC-SA, CC-BY-NC-ND
animated	boolean (string)	Yes	"true" \| "false"
public	boolean (string)	Yes	"true" \| "false"
video	string	No	YouTube URL (optional)
vox	File	Yes	.vox model file
cover	File	Yes	Image file (thumbnail/preview)

cURL example


curl 'https://voxbox.store/api/model/upload'   -X POST   -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:150.0) Gecko/20100101 Firefox/150.0'   -H 'Accept: */*'   -H 'Accept-Language: en-US,en;q=0.9'   -H 'Accept-Encoding: gzip, deflate, br, zstd'   -H 'Referer: https://voxbox.store/upload'   -H 'Content-Type: multipart/form-data; boundary=----geckoformboundaryda415da44f71c620b7e0b435ea1a4280'   -H 'Origin: https://voxbox.store'   -H 'DNT: 1'   -H 'Sec-GPC: 1'   -H 'Connection: keep-alive'   -H 'Cookie: jwt=*here goes your JWT*'   -H 'Sec-Fetch-Dest: empty'   -H 'Sec-Fetch-Mode: cors'   -H 'Sec-Fetch-Site: same-origin'   -H 'Priority: u=0'   --data-binary   $'------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="name"

Test
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="description"

ttest
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="category"

Vehicle
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="animated"

true
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="cover"; filename="Screenshot 2026-04-30 at 10.11.15.png"
Content-Type: image/png

------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="vox"; filename="axe.vox"
Content-Type: application/octet-stream

------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="license"

CC-0
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280
Content-Disposition: form-data; name="public"

false
------geckoformboundaryda415da44f71c620b7e0b435ea1a4280--
'

Response

{
  "id": "model_id",
  "status": "success"
}

PATCH /api/model/update

Update an existing model (new version if .vox is provided).

Headers

Header	Value	Required	Details
Cookie	jwt=refresh jwt	Yes	Refresh JWT used for authentication
Content-Type	multipart/form-data	Yes	Required for file uploads

Body

Field	Type	Required	Details
id	string	Yes	Model identifier
name	string	No	2–64 characters
description	string	No	Max 512 characters
category	enum	No	Character, Environment, Prop, Vegetation, Vehicle, Random, Weapon, Architecture
license	enum	No	CC-0, CC-BY, CC-BY-SA, CC-BY-ND, CC-BY-NC, CC-BY-NC-SA, CC-BY-NC-ND
animated	boolean (string)	No	"true" \| "false"
public	boolean (string)	No	"true" \| "false"
video	string	No	YouTube URL
vox	File	No	.vox model file (creates new version if provided)
cover	File	No	Image file (thumbnail/preview)

GET /api/model/search

Search and paginate models with filtering by category, license, rating, size, upload period, and more.

Headers

Header	Value	Required	Details
Cookie	jwt=refresh jwt	Yes	Refresh JWT used for authentication

Query Parameters

Parameter	Type	Required	Details
sortOrder	enum	No	Sort direction. ASC \| DESC. Defaults to DESC.
page	integer	No	Zero-indexed page number. Defaults to 0.
count	integer	No	Results per page. Defaults to 32.
sortBy	enum	No	Column to sort by. name, uploadTime, size, rating. Defaults to uploadTime.
userId	string	No	Filter by model creator user ID.
username	string	No	Case-insensitive substring match on the creator's username.
name	string	No	Case-insensitive substring match on the model name.
categories	enum[]	No	One or more categories. Accepts a single value or repeated keys. Character, Environment, Prop, Vegetation, Vehicle, Random, Weapon, Architecture
licenses	enum[]	No	One or more licenses. Accepts a single value or repeated keys. CC-0, CC-BY, CC-BY-SA, CC-BY-ND, CC-BY-NC, CC-BY-NC-SA, CC-BY-NC-ND
animated	boolean (string)	No	"true" \| "false"
size	RangeDto	No	File size range in MB. Clamped to configured max. Converted to bytes internally. Defaults to full range.
uploadPeriod	RangeDto	No	Unix timestamp range (ms). Clamped to [0, now]. Defaults to full range.
rating	RangeDto	No	Rating range clamped to configured min/max. Defaults to full range.

RangeDto: { start: number, end: number }

Example request

https://voxbox.store/api/model/search?uploadPeriod%5Bstart%5D=1776853156173&uploadPeriod%5Bend%5D=1778623200000&size%5Bstart%5D=1.9&size%5Bend%5D=6.9&rating%5Bstart%5D=2&rating%5Bend%5D=3.3&username=TestCreator&animated=true&categories%5B0%5D=Environment&categories%5B1%5D=Vehicle&name=TestName&sortBy=size&sortOrder=ASC&licenses%5B0%5D=CC-BY&licenses%5B1%5D=CC-BY-NC-ND

Response

{
  "data": [
    {
      "id": "fhs7808ysc",
      "userId": "jH1JS0P3WJ",
      "username": "mgerhardy",
      "name": "caveexpress npc mammoth",
      "description": "",
      "category": "Character",
      "video": null,
      "animated": false,
      "public": true,
      "license": "CC-0",
      "uploadTime": 1742541224241,
      "lastUpdateTime": 1742552094582,
      "voxFile": "caveexpress-npc-mamut.vox",
      "size": 895231,
      "price": 0,
      "totalRatings": 1,
      "rating": 5,
      "featured": false,
      "versions": [
        {
          "number": 1,
          "modelId": "fhs7808ysc",
          "uploadTime": 1742541224241,
          "endTime": null
        }
      ]
    }
  ],
  "count": 1
}

The count value is the total number of entities that match the query, not the amount of returned objects.