API documentation
Base URL https://assets.codestream.tech
Authentication
Create a key on the API Keys page and send it with every /api/v1 request, using either header:
X-API-Key: aiq_xxxxxxxx_… Authorization: Bearer aiq_xxxxxxxx_…
Keys carry scopes: read lists, gets and downloads; write uploads, edits and deletes.
Endpoints
POST/api/v1/assetswriteMultipart upload. Parts:
file (required), name, folder, tags (comma separated). Returns 201 with the asset JSON.GET/api/v1/assetsreadList assets. Query:
q, folder (/ = root only), tag, skip, take (max 100).GET/api/v1/assets/{id}readAsset metadata.
GET/api/v1/assets/{id}/filereadDownload the original file.
PATCH/api/v1/assets/{id}writeJSON body with any of
name, folder, tags (array).DELETE/api/v1/assets/{id}writeDelete an asset. Returns
204.GET/i/{id}publicImage delivery with on-the-fly transforms. No key needed, since the unguessable id acts as the secret.
Transformations /i/{id}?…
| Parameter | Values |
|---|---|
w, h | Output width / height in px (1–4096). One alone keeps the aspect ratio. |
fit | cover (default, crop to fill) · contain (fit inside) · fill (stretch) · pad (letterbox) |
format | original (default) · jpg · png · webp |
q | Quality 1–100 (JPEG / WebP) |
rotate | Any multiple of 90 |
flip | h, v or hv |
blur | 0–50 |
grayscale | 1 to enable |
dl | 1 to download as an attachment |
Transformed output has EXIF and location metadata removed. Unknown parameters are ignored, so cache-busting params work; invalid values return 400.
Examples
# upload curl -X POST https://assets.codestream.tech/api/v1/assets \ -H "X-API-Key: $KEY" \ -F "[email protected]" -F "folder=products" -F "tags=summer,hero" # search curl "https://assets.codestream.tech/api/v1/assets?q=hero&take=10" -H "X-API-Key: $KEY" # 400x400 WebP thumbnail (public) curl -o thumb.webp "https://assets.codestream.tech/i/{id}?w=400&h=400&fit=cover&format=webp" # update tags curl -X PATCH https://assets.codestream.tech/api/v1/assets/{id} -H "X-API-Key: $KEY" \ -H "Content-Type: application/json" -d '{"tags":["sale"]}' # delete curl -X DELETE https://assets.codestream.tech/api/v1/assets/{id} -H "X-API-Key: $KEY"
Errors
Errors are JSON: {"error": "message"}
400 invalid input401 missing / invalid / revoked key403 missing scope
404 not found413 too large429 rate limited