Developer Docs

BitSoul 3D — API Reference

All API endpoints accept the X-API-Key header. Your key is shown on your account dashboard. API access is included on the Studio tier; see pricing.

Authentication

Send your API key in the X-API-Key request header on every authenticated call:

X-API-Key: bsm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown once on signup and viewable on your account dashboard. Rotate a compromised key from the dashboard's "Regenerate" button.

Quickstart — download a model

cURL

curl -L -o model.glb \
  -H "X-API-Key: YOUR_API_KEY" \
  https://bitsoulhosting.com/marketplace/api/models/MODEL_ID/download

Python

import requests

resp = requests.get(
    "https://bitsoulhosting.com/marketplace/api/models/MODEL_ID/download",
    headers={"X-API-Key": "YOUR_API_KEY"},
    stream=True,
)
resp.raise_for_status()
with open("model.glb", "wb") as f:
    for chunk in resp.iter_content(8192):
        f.write(chunk)

Endpoints

GET/api/models

List models in the catalog. Public — no API key required.

Query param	Type	Description
`q`	string	Free-text search
`category`	string	Filter by category slug
`page`	integer	Page number (default 1)
`limit`	integer	Page size (max 100, default 24)

GET/api/models/:id

Fetch a single model's metadata. Public.

GET/api/models/:id/download

Authenticated. Returns the model file as a binary stream. Counts against your monthly quota.

Errors: 401 invalid key · 429 monthly limit reached (response body includes quota).

GET/api/members/me

Authenticated. Returns your member profile, current tier, monthly download quota, and subscription state.

GET/api/favorites

Authenticated. List your saved models with thumbnails and metadata.

POST/api/favorites/:modelId

Authenticated. Add a model to your favorites. Free tier capped at 10; 403 with upgrade_required:true if exceeded.

DELETE/api/favorites/:modelId

Authenticated. Remove a model from your favorites.

GET/api/downloads/history

Authenticated. Recent downloads in reverse-chronological order.

Query param	Type	Description
`limit`	integer	Max rows to return (1–200, default 50)

GET/api/config

Public. Tier prices, feature lists, and PayPal client ID.

Rate limits & quotas

Monthly download quota is enforced per plan (Free 2, Indie 25, Pro 100, Studio unlimited).
Quota resets on the first of each month.
A 429 response always includes { quota: { used, limit, remaining } }.

Need help?

Email [email protected] or open a ticket from the support form. Studio members get a dedicated account manager.

Get a free 3D model when you join — plus new-drop alerts.
Drops + new bundle alerts. No spam. Unsubscribe anytime.