Getting started

Quick facts

• API base URL: https://upload.basix.media/api/v1. Every endpoint answers there.
• Auth: Authorization: Bearer bx_live_... on every request.
• CDN addresses: https://cdn.basix.media/<publicId>/<path>. Your publicId is 8 characters, returned by GET /api/v1/me.
• Uploads: multipart POST https://upload.basix.media/api/v1/upload with a file field and an optional path field.
• Errors: { "error": { "code": "...", "message": "..." } } with a matching HTTP status on /api/v1 endpoints. The compatible endpoints use their own shape (see below).
• Sizes: strings in list, detail and stats responses ("size": "15320"). Numbers in upload responses ("size": 15320).
• Max file size: 2048 MB. Images, video and audio only. The type is detected from the bytes, never from the name.
• https://basix.media/api/v1/... also answers the /api/v1 endpoints, but uploads above 100 MB fail there and the compatible endpoints are not served there. Use upload.basix.media for everything.

Getting started

1. Create an account at https://basix.media.
2. Create an API key in Dashboard → API (https://basix.media/dashboard/api). The key is shown once. Store it in an environment variable or a server convar.
3. Check the key and read your publicId:

curl https://upload.basix.media/api/v1/me \
  -H "Authorization: Bearer $BASIX_KEY"

Response:

{
  "organization": { "name": "My Server", "publicId": "a7k2m9x4" },
  "key": { "scope": "upload" },
  "quota": { "bytes": "10737418240", "canUpload": true, "reason": null },
  "used": { "bytes": "52428800", "files": 42, "fileBytes": "50331648", "logBytes": "2097152", "databaseBytes": "0" },
  "plan": null,
  "subscription": null
}

4. Upload a file:

curl -X POST https://upload.basix.media/api/v1/upload \
  -H "Authorization: Bearer $BASIX_KEY" \
  -F "path=items/burger.png" \
  -F "[email protected]"

5. Use the url from the response anywhere: an <img> tag, an email, a database row, a Discord message.