API Documentation

Everything you need to integrate Altarion Media into an application.

Authentication

All API requests need an API key in the x-api-key header. ntk_ keys belong to a client team and are the ones to use in a client integration; nsk_ keys are personal.

GET https://apimedia.altarionsystems.co.ke/api/folders
x-api-key: ntk_your_team_key_here

Team keys are generated per client from the Teams page; personal keys from Settings.

Uploading Files

Uploads are three steps: get a presigned URL, PUT the bytes straight to Cloudflare R2, then confirm. The API never handles the file bytes.

Step 1 — Get upload URL

POST https://apimedia.altarionsystems.co.ke/api/files/upload-url
x-api-key: ntk_your_team_key

{
  "name": "photo.jpg",
  "type": "image/jpeg",
  "size": 2048000,
  "folderUuid": "optional-folder-uuid"
}

// Response
{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned.url/...",
    "key": "userId/folderUuid/abc123.jpg",
    "cdnUrl": "https://rs.altarionsystems.co.ke/..."
  }
}

Step 2 — Upload to R2

PUT presignedUrl
Content-Type: image/jpeg
[file bytes]

Step 3 — Confirm upload

POST https://apimedia.altarionsystems.co.ke/api/files/confirm
x-api-key: ntk_your_team_key

{
  "key": "userId/folderUuid/abc123.jpg",
  "name": "photo.jpg",
  "type": "image",
  "mimeType": "image/jpeg",
  "generateVariantsFlag": true   // generates thumb, sm, md, lg WebP variants
}

// size is read from R2, not from this body — it is what
// the quota is charged against.

Image Transforms

Transform any image on the fly through the transform endpoint. It only serves keys you own or that are marked public.

Param	Type	Description
`w`	number	Width in pixels (max 4000)
`h`	number	Height in pixels (max 4000)
`q`	number	Quality 1–100 (default: 82)
`f`	string	Format: webp, jpeg, png, avif
`fit`	string	Resize mode: cover, contain, fill, inside, outside

// Via transform endpoint
GET https://apimedia.altarionsystems.co.ke/api/files/transform?key=your-file-key&w=800&f=webp&q=80

// Variants generated at upload time are served straight
// from the CDN — no transform call needed:
file.variants.thumb | .sm | .md | .lg

Folders

GET  https://apimedia.altarionsystems.co.ke/api/folders                // list home folder contents
GET  https://apimedia.altarionsystems.co.ke/api/folders?folder=uuid    // list specific folder
POST https://apimedia.altarionsystems.co.ke/api/folders                // create folder
PUT  https://apimedia.altarionsystems.co.ke/api/folders/:uuid          // rename folder
DELETE https://apimedia.altarionsystems.co.ke/api/folders/:uuid        // delete folder + contents