Media uploads

The Media API has two upload endpoints depending on how your environment handles file data.

Endpoints

Both endpoints return the same response shape.

Response shape

{
  "id": "01HXYZ...",
  "org_id": "01HABC...",
  "filename": "screenshot.png",
  "content_type": "image/png",
  "size": 204800,
  "sha256": "a3f2...",
  "url": "https://cdn.serverops.gg/...",
  "created_at": "2024-05-15T10:30:00Z"
}

• id: ULID - unique, sortable identifier
• url: CDN URL - publicly accessible, use this to share or display the file
• sha256: content hash for integrity verification

Multipart upload

curl -X POST https://api.serverops.gg/v1/media \
  -H "Authorization: Bearer so_live_..." \
  -F "[email protected]"

The field name must be file. Filename and content type are inferred from the upload.

Base64 upload

For environments without multipart support, encode the file as base64 and send it as JSON:

curl -X POST https://api.serverops.gg/v1/media/base64 \
  -H "Authorization: Bearer so_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file": "<base64-encoded-bytes>",
    "filename": "screenshot.png"
  }'

Encoding files as base64

Node.js

const fs = require('fs');
const base64 = fs.readFileSync('screenshot.png').toString('base64');

Go

data, _ := os.ReadFile("screenshot.png")
base64Data := base64.StdEncoding.EncodeToString(data)

Java

byte[] bytes = Files.readAllBytes(Path.of("screenshot.png"));
String base64 = Base64.getEncoder().encodeToString(bytes);

File size limits

Files exceeding the limit return 413 Content Too Large with code file_too_large.

Supported file types

The API accepts common image, video, and document formats:

• Images: image/png, image/jpeg, image/gif, image/webp
• Video: video/mp4, video/webm
• Documents: application/pdf

Unsupported types return 415 Unsupported Media Type with code unsupported_type.

Listing and deleting files

List files (with pagination):

curl https://api.serverops.gg/v1/media \
  -H "Authorization: Bearer so_live_..."

Delete a file:

curl -X DELETE https://api.serverops.gg/v1/media/{id} \
  -H "Authorization: Bearer so_live_..."

Deleted files are soft-deleted for 30 days before permanent removal.

CDN behaviour

File URLs are permanent and publicly accessible by default - anyone with the URL can view the file. If you need access control, store the file ID and serve the URL only to authorised users in your own application.

Deduplication

The API does not deduplicate uploads. Uploading the same file twice creates two separate records with different IDs. Use the sha256 hash in the response if you need to detect duplicates on your side.