REST API Documentation

Complete reference for programmatic media ingestion, streaming, batch operations, and full error payloads

# Assets Manager (skdm_cloud) - AI Agent Integration Manual & System Instructions

Use this documentation and cURL specifications to interact with the REST API for uploading, managing, streaming, and deleting media files.

---

## 1. System Credentials & Context

- **Base URL**: `https://cloud.skdm.in`
- **Active API Key**: `your_api_key_here`
- **Default Project Identifier**: `proj_my_project`

---

## 2. Authentication Specifications

All private API endpoints require authentication using your API key. Three authentication methods are supported (in order of recommendation):

1. **HTTP Header (Recommended)**: `x-api-key: your_api_key_here`
2. **Authorization Header**: `Authorization: Bearer your_api_key_here`
3. **Query Parameter**: `?api_key=your_api_key_here`

---

## 3. Operations, cURL Commands & Response Catalog

### 3.1. Upload Single Media Asset
Upload a single file (image, video, audio, document, archive) or provide a direct file URL into a project or optional subfolder. Max file size is 500MB.

#### Option A: cURL Binary File Upload (Multipart Form-Data)
```bash
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -F "file=@/path/to/hero.png" \
  -F "folder=marketing/2026"
```

#### Option B: cURL Direct URL Import (JSON Body)
```bash
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/images/hero.png",
    "folder": "marketing/2026"
  }'
```

#### Possible Responses

##### 201 Created (Success)
```json
{
  "success": true,
  "message": "Media uploaded successfully",
  "data": {
    "id": 104,
    "publicUrl": "https://cloud.skdm.in/assets/proj_my_project/1786346617028_hero.png"
  }
}
```

##### 400 Bad Request (Missing File or URL Parameter)
```json
{
  "error": "Missing file parameter or URL. Please attach file(s) under key 'file', 'files', or 'media', or provide URL(s) under key 'url' or 'urls'."
}
```

##### 401 Unauthorized (Invalid or Missing API Key)
```json
{
  "error": "Unauthorized. Valid API key required via x-api-key header, Authorization: Bearer <key>, or api_key query parameter."
}
```

##### 404 Not Found (Project Not Found)
```json
{
  "error": "Project not found for identifier 'proj_my_project'"
}
```

##### 408 Request Timeout (Upload Task Timed Out > 60s)
```json
{
  "error": "Upload process timed out"
}
```

##### 422 Unprocessable Entity (Storage / Disk / Download Error)
```json
{
  "error": "Failed to save media: :enospc"
}
```

##### 500 Internal Server Error (Process Crash / Unhandled Server Error)
```json
{
  "error": "Internal server error during upload processing."
}
```

---

### 3.2. Batch Upload Multiple Media Assets
Upload 2 to 20 files in a single atomic multipart request or provide an array of URLs to download and store into a project or optional subfolder. Max 500MB per file.

#### Option A: cURL Multiple Files
```bash
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -F "files[]=@/path/to/photo1.jpg" \
  -F "files[]=@/path/to/photo2.jpg" \
  -F "folder=products/summer"
```

#### Option B: cURL Multiple URLs
```bash
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/photo1.jpg",
      "https://example.com/photo2.jpg"
    ],
    "folder": "products/summer"
  }'
```

#### Possible Responses

##### 201 Created (Success)
```json
{
  "success": true,
  "message": "Media uploaded successfully",
  "data": [
    {
      "id": 104,
      "publicUrl": "https://cloud.skdm.in/assets/proj_my_project/1786346617028_photo1.jpg"
    },
    {
      "id": 105,
      "publicUrl": "https://cloud.skdm.in/assets/proj_my_project/1786346617029_photo2.jpg"
    }
  ]
}
```

##### 400 Bad Request (Batch Limit Exceeded > 20 files/URLs)
```json
{
  "error": "Maximum 20 files/URLs allowed per upload request."
}
```

##### 400 Bad Request (Missing Files or URLs)
```json
{
  "error": "Missing file parameter or URL. Please attach file(s) under key 'file', 'files', or 'media', or provide URL(s) under key 'url' or 'urls'."
}
```

##### 401 Unauthorized (Invalid or Missing API Key)
```json
{
  "error": "Unauthorized. Valid API key required via x-api-key header, Authorization: Bearer <key>, or api_key query parameter."
}
```

##### 404 Not Found (Project Not Found)
```json
{
  "error": "Project not found for identifier 'proj_my_project'"
}
```

##### 408 Request Timeout
```json
{
  "error": "Upload process timed out"
}
```

##### 422 Unprocessable Entity
```json
{
  "error": "Failed to save media: :enospc"
}
```

##### 500 Internal Server Error
```json
{
  "error": "Internal server error during upload processing."
}
```

---

### 3.3. Public Media Streaming & CDN Delivery
Public high-speed binary streaming endpoint for frontend embedding and direct asset downloading. No authentication required.

#### cURL Request
```bash
# Stream root asset
curl -I "https://cloud.skdm.in/assets/proj_my_project/4a9e2b1f_banner.png"

# Stream asset in nested subfolder
curl -I "https://cloud.skdm.in/assets/proj_my_project/marketing/2026/4a9e2b1f_banner.png"
```

#### Possible Responses

##### 200 OK (Binary Stream Headers)
```http
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 489201
Cache-Control: public, max-age=31536000, immutable
Accept-Ranges: bytes
```

##### 404 Not Found (Asset Missing)
```json
{
  "error": "Asset '4a9e2b1f_banner.png' not found for project 'proj_my_project'"
}
```

---

### 3.4. Delete Single Media Asset
Permanently remove a single stored media file from a project container and storage disk.

#### cURL Request
```bash
curl -X DELETE "https://cloud.skdm.in/api/projects/proj_my_project/assets/4a9e2b1f_banner.png" \
  -H "x-api-key: your_api_key_here"
```

#### Possible Responses

##### 200 OK (Success)
```json
{
  "message": "Media asset deleted successfully",
  "file_name": "4a9e2b1f_banner.png"
}
```

##### 401 Unauthorized (Invalid or Missing API Key)
```json
{
  "error": "Unauthorized. Valid API key required via x-api-key header, Authorization: Bearer <key>, or api_key query parameter."
}
```

##### 404 Not Found (Project or Asset Not Found)
```json
{
  "error": "Media asset '4a9e2b1f_banner.png' not found in project 'proj_my_project'"
}
```

---

### 3.5. Batch Delete Media Assets
Atomically delete multiple media assets in a single JSON payload.

#### cURL Request
```bash
curl -X DELETE "https://cloud.skdm.in/api/projects/proj_my_project/assets" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filenames": [
      "4a9e2b1f_photo1.jpg",
      "8c7d6e5a_photo2.jpg"
    ]
  }'
```

#### Possible Responses

##### 200 OK (Success)
```json
{
  "success": true,
  "message": "2 media assets deleted successfully",
  "deleted_filenames": [
    "4a9e2b1f_photo1.jpg",
    "8c7d6e5a_photo2.jpg"
  ]
}
```

##### 400 Bad Request (Empty or Missing Filenames List)
```json
{
  "error": "Please provide a non-empty list of filenames under key 'filenames'."
}
```

##### 401 Unauthorized (Invalid or Missing API Key)
```json
{
  "error": "Unauthorized. Valid API key required via x-api-key header, Authorization: Bearer <key>, or api_key query parameter."
}
```

##### 404 Not Found (Project Not Found)
```json
{
  "error": "Project not found for identifier 'proj_my_project'"
}
```

---

## 4. Master HTTP Status Codes Summary Table

| HTTP Code | Name | Description | Example Payload |
| :--- | :--- | :--- | :--- |
| `200` | OK | Successful fetch, streaming, or deletion. | `{"success": true, "message": "Media asset deleted successfully"}` |
| `201` | Created | Asset(s) uploaded and saved to disk. | `{"success": true, "data": {"publicUrl": "https://cloud.skdm.in/..."}}` |
| `400` | Bad Request | Missing file or URL, empty filenames, or >20 batch limit. | `{"error": "Maximum 20 files/URLs allowed per upload request."}` |
| `401` | Unauthorized | Missing or invalid API key credentials. | `{"error": "Unauthorized. Valid API key required..."}` |
| `404` | Not Found | Project identifier or asset filename does not exist. | `{"error": "Project not found for identifier 'proj_xxx'"}` |
| `408` | Request Timeout | Ingestion or download process exceeded 60s deadline. | `{"error": "Upload process timed out"}` |
| `422` | Unprocessable | Persistence write failure, invalid URL, or oversized file (>500MB). | `{"error": "Downloaded file exceeds maximum allowed size of 500MB"}` |
| `500` | Internal Error | Process termination or unhandled server crash. | `{"error": "Internal server error during upload processing."}` |

Viewing with placeholder keys Sign in for your keys

Jump To: Authentication Errors & Status Codes Upload Media Delete Single Batch Delete Public Streaming

Authentication

All REST API endpoints require authentication using your account API Key.

You can pass your API key in any of the following 3 standard formats:

1. Header x-api-key

Recommended for backend servers and API clients.

2. Header Authorization

Standard Bearer <key> token header.

3. Query Param

Append ?api_key=<key> to request URL.

Error Handling & HTTP Status Codes

Comprehensive overview of standard error payloads and HTTP status codes returned by the API.

When any request fails, the API responds with standard HTTP status codes and a JSON body containing a descriptive error field. This makes error parsing reliable across all programming languages.

Standard Error JSON Schema Content-Type: application/json

{
                    "error": "Descriptive explanation of why the request was rejected."
                  }

HTTP Status Codes Reference & Meanings

400 Bad Request

Missing or Invalid Request Payload

Triggered when required fields (like file or filenames) are missing, empty, or if more than 20 files are submitted in one upload.

401 Unauthorized

Authentication Failed

API Key is absent from request headers/parameters or does not match any registered account.

404 Not Found

Resource Not Found

The specified project identifier does not belong to the user, or the target media asset filename does not exist.

408 Timeout

Ingestion Timeout

Asynchronous background file ingestion supervisor exceeded the 30-second timeout threshold.

422 Unprocessable

File Storage / IO Failure

Server was unable to persist file to disk storage (e.g. disk space exhausted or write permission error).

500 Server Error

Internal Server Error

An unhandled backend process failure or unexpected supervisor task termination occurred.

POST /api/projects/:identifier/upload

Upload Media Assets

Upload 1 to 20 media files (images, videos, audio, documents, archives) or direct public URLs (max 500MB each) into a project or subfolder.

Path Parameters

identifier required string

The unique project identifier (e.g. proj_my_project).

Request Payload Fields (Multipart Form-Data or JSON)

file or files or media file or url required binary file(s)

Binary file payload via multipart form-data. Attach single or multiple files (max 20 files per request, max 500MB each).

url or urls or file_url file or url required string or array

Direct HTTP/HTTPS link(s) to download and store. Supported in JSON body or form fields (max 20 URLs per request, max 500MB each).

filename optional string

Optional custom filename override when importing a single file from URL.

folder or folder_name optional string

Target subfolder path (e.g. marketing/2026). Creates folders automatically if non-existent.

Possible Response Payloads

201 Created Single File Upload Success

{
  "success": true,
  "message": "Media uploaded successfully",
  "data": {
    "id": 104,
    "publicUrl": "https://cloud.skdm.in/assets/proj_my_project/a9f1b2c3_banner.png"
  }
}

400 Bad Request Missing File Parameter

{
  "error": "Missing file parameter or URL. Please attach file(s) under key 'file', 'files', or 'media', or provide URL(s) under key 'url' or 'urls'."
}

400 Bad Request Batch Limit Exceeded (>20 files)

{
  "error": "Maximum 20 files/URLs allowed per upload request."
}

401 Unauthorized Invalid or Missing API Key

{
  "error": "Unauthorized. Valid API key required via x-api-key header, Authorization: Bearer <key>, or api_key query parameter."
}

404 Not Found Project Not Found

{
  "error": "Project not found for identifier 'proj_my_project'"
}

422 Unprocessable Disk Persistence Failure

{
  "error": "Failed to save media: :enospc"
}

DELETE /api/projects/:identifier/assets/:filename

Delete Single Media Asset

Permanently remove a stored asset from the project container and underlying disk storage.

Path Parameters

identifier required string

Project identifier.

filename required string

The internal unique storage filename of the asset (e.g. 4a9e2b1f_banner.png).

Possible Response Payloads

200 OK Asset Deleted Successfully

{
  "message": "Media asset deleted successfully",
  "file_name": "4a9e2b1f_banner.png"
}

404 Not Found Asset Filename Not Found in Project

{
  "error": "Media asset '4a9e2b1f_banner.png' not found in project 'proj_my_project'"
}

DELETE /api/projects/:identifier/assets

Batch Delete Media Assets

Delete multiple media assets in a single atomic API call.

JSON Body Payload

filenames required string[]

A JSON array containing the storage filenames to delete.

Possible Response Payloads

200 OK Batch Deletion Success

{
  "success": true,
  "message": "2 media assets deleted successfully",
  "deleted_filenames": [
    "4a9e2b1f_photo1.jpg",
    "8c7d6e5a_photo2.jpg"
  ]
}

400 Bad Request Empty or Missing Filenames List

{
  "error": "Please provide a non-empty list of filenames under key 'filenames'."
}

404 Not Found Project Not Found

{
  "error": "Project not found for identifier 'proj_my_project'"
}

GET /assets/:identifier/*path

Public Media Streaming & CDN Delivery

High-speed streaming endpoint for serving images, streaming HTML5 video/audio with byte-range seeks, and downloading documents.

This route is completely public (no auth header needed) and is optimized for direct inclusion in <img src="...">, <video>, or frontend applications.

Included HTTP Response Headers:

Cache-Control: public, max-age=31536000, immutable (1 year browser & CDN cache)
Content-Type: <detected MIME type>
Accept-Ranges: bytes (Fast video scrubber seeking)

Possible Response Payloads

200 OK Binary Stream Headers

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 489201
Cache-Control: public, max-age=31536000, immutable
Accept-Ranges: bytes

<Binary Stream: https://cloud.skdm.in/assets/proj_my_project/4a9e2b1f_banner.png>

404 Not Found Asset File Not Found

{
  "error": "Asset 'banner.png' not found for project 'proj_my_project'"
}

Upload Asset Console

# Option A: Upload binary file (multipart/form-data, max 500MB)
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -F "file=@/path/to/banner.png" \
  -F "folder=marketing/2026"

# Option B: Upload via direct file URL (downloaded and stored by server, max 500MB)
curl -X POST "https://cloud.skdm.in/api/projects/proj_my_project/upload" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/assets/banner.png",
    "folder": "marketing/2026"
  }'

Response Explorer

201 Created

{
  "success": true,
  "message": "Media uploaded successfully",
  "data": {
    "id": 104,
    "publicUrl": "https://cloud.skdm.in/assets/proj_my_project/a9f1b2c3_banner.png"
  }
}

Delete Assets Console

curl

curl -X DELETE "https://cloud.skdm.in/api/projects/proj_my_project/assets" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filenames": [
      "4a9e2b1f_photo1.jpg",
      "8c7d6e5a_photo2.jpg"
    ]
  }'

Response Explorer

200 OK (Batch)

{
  "success": true,
  "message": "2 media assets deleted successfully",
  "deleted_filenames": [
    "4a9e2b1f_photo1.jpg",
    "8c7d6e5a_photo2.jpg"
  ]
}

Streaming HTML / Delivery

Public URL

<!-- HTML Image / CDN Embedding -->
<img src="https://cloud.skdm.in/assets/proj_my_project/4a9e2b1f_banner.png" alt="Banner" />

<!-- HTML5 Video / Audio Streaming with seek ranges -->
<video controls src="https://cloud.skdm.in/assets/proj_my_project/marketing/promo.mp4"></video>

Delivery Explorer

200 OK (Binary Stream)

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 489201
Cache-Control: public, max-age=31536000, immutable
Accept-Ranges: bytes

<Binary Stream: https://cloud.skdm.in/assets/proj_my_project/4a9e2b1f_banner.png>