SDK Documentation

ArtaCDN SDK Documentation

Complete guide to uploading media, image transformations, and CDN delivery

Quick Start

Get started in under 5 minutes

1. Get your API Key

Go to the API Keys section in your dashboard and create a new API key.

2. Install the SDK

NPM (recommended for Node.js/React/Next.js):

pnpm add @artatol-acp/artacdn

CDN (for vanilla JavaScript):

<script src="https://artacdn.artatol.net/sdk/artacdn.min.js"></script>

3. Upload your first file

import ArtaCDN from '@artatol-acp/artacdn';

const cdn = new ArtaCDN({
  apiKey: 'acp_sk_your_api_key_here'
});

// Upload a file
const file = document.querySelector('input[type="file"]').files[0];
const result = await cdn.upload(file, { bucketId: 'your-bucket-id' });

console.log(result.id);   // UUID of uploaded file
console.log(result.type); // 'image', 'audio', 'video', or 'file'
console.log(result.url);  // Direct URL to file

Supported Media Types

ArtaCDN automatically detects and handles different file types

Images

JPEG, PNG, WebP, GIF, SVG, HEIC

Auto-optimization, variants, on-the-fly transforms

Audio

MP3, WAV, AAC, OGG, FLAC, M4A

Streaming with range requests, metadata extraction

Growth+ tier

Video

MP4, MOV, WebM, AVI, MKV

Streaming, auto-generated thumbnails

Growth+ tier

Files

PDF, ZIP, documents, and more

Direct download with proper headers

URL Formats

Clean URLs for serving media files

Images

# Predefined variant

https://artacdn.artatol.net/image/thumb/:uuid.webp

https://artacdn.artatol.net/image/medium/:uuid.webp

https://artacdn.artatol.net/image/large/:uuid.jpg

# Custom size

https://artacdn.artatol.net/image/600x400/cover/:uuid.webp

https://artacdn.artatol.net/image/800x/:uuid.jpg

# With filters

https://artacdn.artatol.net/image/large/filters:quality(90):sharpen/:uuid.webp

# With watermark

https://artacdn.artatol.net/image/large/filters:watermark(wm-uuid,-45)/:uuid.jpg

Audio

https://artacdn.artatol.net/audio/:uuid

https://artacdn.artatol.net/audio/:uuid?download=true

Video

https://artacdn.artatol.net/video/:uuid

https://artacdn.artatol.net/video/:uuid/thumbnail

Files

https://artacdn.artatol.net/files/:uuid

Predefined Image Variants

Automatically generated when you upload an image

Variant	Max Width	Quality	Best For
`thumb`	256px	90%	Thumbnails, gallery previews
`small`	480px	85%	Mobile images
`medium`	768px	85%	Tablet, content images
`large`	1024px	85%	Desktop, hero images
`xlarge`	1920px	85%	Full HD displays
`xxlarge`	2560px	85%	4K/Retina displays

SDK Methods

Generate optimized image URL

// Predefined variant
cdn.getUrl(uuid, { variant: 'medium', format: 'webp' });
// → https://artacdn.artatol.net/image/medium/uuid.webp

// Custom size
cdn.getUrl(uuid, { width: 600, height: 400, fit: 'cover', format: 'jpg' });
// → https://artacdn.artatol.net/image/600x400/cover/uuid.jpg

// With watermark
cdn.getUrl(uuid, {
  variant: 'large',
  watermark: { uuid: 'watermark-uuid', angle: -45 }
});

Generate responsive srcset

const srcset = cdn.getSrcSet(uuid, { format: 'webp' });
// → "...thumb/uuid.webp 256w, ...small/uuid.webp 480w, ...medium/uuid.webp 768w, ..."

// Use in HTML
<img src={cdn.getUrl(uuid, { variant: 'medium' })} srcset={srcset} />

Audio & Video URLs

// Audio
cdn.getAudioUrl(uuid);           // Streaming
cdn.getAudioUrl(uuid, true);     // Force download

// Video
cdn.getVideoUrl(uuid);           // Streaming
cdn.getVideoThumbnailUrl(uuid);  // Auto-generated thumbnail

Delete a file

await cdn.delete(uuid);

Private Buckets & Signed URLs

Secure access to files in private buckets

Files in private buckets require signed URLs for access. Generate them server-side:

// Single signed URL
const result = await cdn.getSignedUrl({
  fileId: uuid,
  type: 'image',
  variant: 'medium',
  format: 'webp',
  expiresIn: 3600 // 1 hour
});
console.log(result.url);
// → https://artacdn.artatol.net/image/medium/uuid.webp?sig=...&exp=...

// Batch signed URLs (up to 100)
const batch = await cdn.getSignedUrls([
  { fileId: 'uuid1', type: 'image', variant: 'thumb' },
  { fileId: 'uuid2', type: 'audio' },
  { fileId: 'uuid3', type: 'video' }
]);

React / Next.js Integration

Use the @artatol-acp/artacdn-nextjs package for React hooks

pnpm add @artatol-acp/artacdn-nextjs

import { ArtaCDNProvider, useFileUpload, useImageUrl } from '@artatol-acp/artacdn-nextjs';

function App() {
  return (
    <ArtaCDNProvider apiKey="your-api-key">
      <Uploader />
    </ArtaCDNProvider>
  );
}

function Uploader() {
  const { upload, uploading, progress } = useFileUpload();

  const handleUpload = async (file: File) => {
    const result = await upload(file, { bucketId: 'your-bucket-id' });
    console.log('Uploaded:', result.id);
  };

  return (
    <div>
      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
      {uploading && <p>Progress: {progress?.percentage}%</p>}
    </div>
  );
}

function DisplayImage({ imageId }) {
  const { url } = useImageUrl(imageId, { variant: 'medium', format: 'webp' });
  return <img src={url} alt="" />;
}

REST API Reference

All API endpoints require Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer acp_sk_your_api_key_here

POST

/api/v1/upload

Upload a file (image, audio, video, or generic file)

Request (multipart/form-data)

Field	Type	Required	Description
file	File	Yes	The file to upload
bucketId	string	Yes	Target bucket UUID
folderId	string	No	Target folder UUID (defaults to Uncategorized)

cURL Example

curl -X POST https://artacdn.artatol.net/api/v1/upload \
  -H "Authorization: Bearer acp_sk_xxx" \
  -F "file=@/path/to/image.jpg" \
  -F "bucketId=your-bucket-uuid" \
  -F "folderId=your-folder-uuid"

Response

{
  "success": true,
  "file": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "image",
    "url": "https://artacdn.artatol.net/api/image/550e8400-e29b-41d4-a716-446655440000",
    "optimized": false
  }
}

GET

/api/v1/files/:uuid

Get file metadata

cURL Example

curl https://artacdn.artatol.net/api/v1/files/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer acp_sk_xxx"

Response (Image)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image",
  "bucket_id": "bucket-uuid",
  "mime_type": "image/jpeg",
  "size_bytes": 1048576,
  "width": 1920,
  "height": 1080,
  "optimized": true,
  "created_at": "2024-01-15T10:30:00Z"
}

DELETE

/api/v1/files/:uuid

Delete a file from R2 storage and database

cURL Example

curl -X DELETE https://artacdn.artatol.net/api/v1/files/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer acp_sk_xxx"

Response

{ "success": true }

POST

/api/v1/files/:uuid/move

Move a file to a different folder (same bucket only)

Request Body (JSON)

{ "folderId": "target-folder-uuid" }

cURL Example

curl -X POST https://artacdn.artatol.net/api/v1/files/file-uuid/move \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"folderId": "target-folder-uuid"}'

GET

/api/v1/buckets

List all buckets for your account

cURL Example

curl https://artacdn.artatol.net/api/v1/buckets \
  -H "Authorization: Bearer acp_sk_xxx"

Response

{
  "success": true,
  "buckets": [
    {
      "id": "bucket-uuid",
      "name": "My Bucket",
      "slug": "my-bucket",
      "is_default": true,
      "is_public": true,
      "file_count": 150,
      "total_size_bytes": "52428800",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST

/api/v1/buckets

Create a new bucket

Request Body (JSON)

{
  "name": "My New Bucket",
  "slug": "my-new-bucket"
}

cURL Example

curl -X POST https://artacdn.artatol.net/api/v1/buckets \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Bucket", "slug": "my-new-bucket"}'

GET

/api/v1/folders?bucketId=xxx

List all folders in a bucket

cURL Example

curl "https://artacdn.artatol.net/api/v1/folders?bucketId=bucket-uuid" \
  -H "Authorization: Bearer acp_sk_xxx"

Response

{
  "success": true,
  "folders": [
    {
      "id": "folder-uuid",
      "name": "Uncategorized",
      "slug": "uncategorized",
      "description": null,
      "is_system": true,
      "file_count": 50,
      "total_size_bytes": "10485760",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "folder-uuid-2",
      "name": "Products",
      "slug": "products",
      "description": "Product images",
      "is_system": false,
      "file_count": 100,
      "total_size_bytes": "41943040",
      "created_at": "2024-01-16T14:00:00Z"
    }
  ]
}

POST

/api/v1/folders

Create a new folder in a bucket

Request Body (JSON)

{
  "bucketId": "bucket-uuid",
  "name": "Products",
  "slug": "products",
  "description": "Product images"
}

cURL Example

curl -X POST https://artacdn.artatol.net/api/v1/folders \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"bucketId": "bucket-uuid", "name": "Products", "slug": "products"}'

PATCH

/api/v1/folders/:id

Update folder name or description

Request Body (JSON)

{
  "name": "New Name",
  "description": "Updated description"
}

cURL Example

curl -X PATCH https://artacdn.artatol.net/api/v1/folders/folder-uuid \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name"}'

DELETE

/api/v1/folders/:id

Delete a folder (moves files to Uncategorized)

cURL Example

curl -X DELETE https://artacdn.artatol.net/api/v1/folders/folder-uuid \
  -H "Authorization: Bearer acp_sk_xxx"

Response

{
  "success": true,
  "message": "Folder deleted. 25 file(s) moved to Uncategorized."
}

Note: System folders (Uncategorized) cannot be deleted.

POST

/api/v1/signed-url

Generate signed URLs for private bucket access

Request Body - Single URL (JSON)

{
  "fileId": "file-uuid",
  "type": "image",
  "variant": "medium",
  "format": "webp",
  "expiresIn": 3600
}

Request Body - Batch URLs (JSON)

{
  "files": [
    { "fileId": "uuid-1", "type": "image", "variant": "thumb" },
    { "fileId": "uuid-2", "type": "audio" },
    { "fileId": "uuid-3", "type": "video" }
  ]
}

cURL Example

curl -X POST https://artacdn.artatol.net/api/v1/signed-url \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "file-uuid", "type": "image", "variant": "medium", "expiresIn": 3600}'

Response (Single)

{
  "url": "https://artacdn.artatol.net/image/medium/uuid.webp?sig=abc123&exp=1705312200",
  "expiresAt": "2024-01-15T12:30:00Z"
}

Response (Batch)

{
  "urls": [
    { "fileId": "uuid-1", "url": "https://artacdn.artatol.net/image/thumb/uuid-1.webp?sig=..." },
    { "fileId": "uuid-2", "url": "https://artacdn.artatol.net/audio/uuid-2?sig=..." },
    { "fileId": "uuid-3", "error": "File not found" }
  ],
  "expiresAt": "2024-01-15T12:30:00Z"
}

Content Pages API (Headless CMS)

Store arbitrary JSON content with automatic image URL resolution

GET

/api/v1/content?bucketId=xxx

List all content pages in a bucket

curl "https://artacdn.artatol.net/api/v1/content?bucketId=bucket-uuid&status=published" \
  -H "Authorization: Bearer acp_sk_xxx"

POST

/api/v1/content

Create a new content page

curl -X POST https://artacdn.artatol.net/api/v1/content \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "bucket-uuid",
    "folderId": "folder-uuid",
    "slug": "homepage-banner",
    "title": "Homepage Banner",
    "data": {
      "heading": "Welcome",
      "imageId": "image-uuid",
      "cta": { "text": "Learn More", "url": "/about" }
    },
    "status": "published"
  }'

GET

/api/v1/content/:slug?bucketId=xxx

Get content page (public, no auth required)

curl "https://artacdn.artatol.net/api/v1/content/homepage-banner?bucketId=bucket-uuid"

Note: Fields named imageId automatically get imageUrl added in response.

PATCH

/api/v1/content/:slug

Update content page

curl -X PATCH https://artacdn.artatol.net/api/v1/content/homepage-banner \
  -H "Authorization: Bearer acp_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"bucketId": "bucket-uuid", "data": {"heading": "New Heading"}}'

DELETE

/api/v1/content/:slug?bucketId=xxx

Delete content page

curl -X DELETE "https://artacdn.artatol.net/api/v1/content/homepage-banner?bucketId=bucket-uuid" \
  -H "Authorization: Bearer acp_sk_xxx"

Error Responses

Common error codes and their meanings

Status	Description
`400`	Bad Request - Missing or invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied or tier limit exceeded
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists (e.g., duplicate slug)
`500`	Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}