Skip to content
Arky Docs

Media API

Manage media files for your business. Media is stored in S3-compatible storage with automatic image optimization and CDN delivery.

Base URL

Section titled “Base URL”

All Media endpoints are prefixed with /v1/businesses/{businessId}.

Authentication

Section titled “Authentication”

Requires Authorization: Bearer <access_token> header.

Upload Media

Section titled “Upload Media”

Upload files or fetch from URLs.

Endpoint: POST /v1/businesses/{businessId}/upload

// Upload files
const files = [
  document.getElementById('fileInput').files[0],
  document.getElementById('fileInput2').files[0],
];


const result = await sdk.media.uploadBusinessMedia({
  files: files,
});


console.log('Uploaded media:', result);
// Returns array of media objects with IDs
// Or upload from URLs
const result = await sdk.media.uploadBusinessMedia({
  urls: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.png',
  ],
});

Response:

{
  "items": [
    {
      "id": "media_abc123",
      "name": "image1.jpg",
      "mimeType": "image/jpeg",
      "size": 245678,
      "url": "business_123/media/abc123.jpg",
      "resolutions": {
        "thumbnail": {
          "url": "business_123/media/abc123_thumb.jpg",
          "width": 150,
          "height": 150
        },
        "medium": {
          "url": "business_123/media/abc123_medium.jpg",
          "width": 800,
          "height": 600
        },
        "original": {
          "url": "business_123/media/abc123.jpg",
          "width": 1920,
          "height": 1080
        }
      },
      "createdAt": 1698765432,
      "updatedAt": 1698765432
    }
  ]
}

Supported File Types

Section titled “Supported File Types”
  • Images: JPG, PNG, GIF, WebP, SVG
  • Videos: MP4, WebM
  • Documents: PDF
  • Other: Any file type (stored as-is)

Automatic Image Processing

Section titled “Automatic Image Processing”

Images are automatically optimized and resized:

  • Thumbnail: 150x150px (cropped)
  • Medium: 800px max width (maintains aspect ratio)
  • Original: Full resolution

Get Media

Section titled “Get Media”

List all media files for your business.

Endpoint: GET /v1/businesses/{businessId}/media

const { items, cursor } = await sdk.media.getBusinessMedia({
  limit: 20,
  cursor: null, // For pagination
});


items.forEach(media => {
  console.log('File:', media.name);
  console.log('Type:', media.mimeType);
  console.log('URL:', media.url);
  console.log('Resolutions:', media.resolutions);
});

Query Parameters:

  • limit (number): Items per page (default: 20, max: 100)
  • cursor (string): Pagination cursor from previous response

Delete Media

Section titled “Delete Media”

Delete a media file.

Endpoint: DELETE /v1/businesses/{businessId}/upload

await sdk.media.deleteBusinessMedia({
  id: 'your-business-id',
  mediaId: 'media_abc123',
});


console.log('Media deleted');

Using Media in Content

Section titled “Using Media in Content”

Media files are referenced in blocks using RELATIONSHIP_MEDIA type:

{
  "key": "gallery",
  "type": "RELATIONSHIP_MEDIA",
  "properties": {
    "maxValues": 10
  },
  "value": [
    "media:abc123",
    "media:def456"
  ]
}

When hydrated (via ?hydrate=true query param), references expand to full media objects.

Building CDN URLs

Section titled “Building CDN URLs”

Media URLs are relative paths. Build full URLs using your storage URL:

const storageUrl = 'https://storage.arky.io';
const media = { url: 'business_123/media/abc123.jpg' };


const fullUrl = `${storageUrl}/${media.url}`;
// "https://storage.arky.io/business_123/media/abc123.jpg"


// Or use SDK utility
const imageUrl = sdk.utils.getImageUrl(mediaBlock, true, storageUrl);

Resolutions

Section titled “Resolutions”

Use different resolutions for performance:

const thumbnail = media.resolutions.thumbnail.url;
const medium = media.resolutions.medium.url;
const original = media.resolutions.original.url;


// Build URLs
const thumbnailUrl = `${storageUrl}/${thumbnail}`;
const mediumUrl = `${storageUrl}/${medium}`;
const originalUrl = `${storageUrl}/${original}`;

Example: File Upload Form

Section titled “Example: File Upload Form”
<form id="uploadForm">
  <input type="file" id="fileInput" multiple accept="image/*" />
  <button type="submit">Upload</button>
</form>


<script>
  document.getElementById('uploadForm').addEventListener('submit', async (e) => {
    e.preventDefault();


    const files = Array.from(document.getElementById('fileInput').files);


    try {
      const result = await sdk.media.uploadBusinessMedia({ files });


      console.log('Uploaded:', result.items.length, 'files');
      result.items.forEach(media => {
        console.log('Media ID:', media.id);
        console.log('URL:', media.url);
      });
    } catch (error) {
      console.error('Upload failed:', error);
    }
  });
</script>

Storage Limits

Section titled “Storage Limits”
  • Max file size: 10MB per file
  • Max files per upload: 10 files
  • Total storage: Depends on your plan
Section titled “Related”