API Documentation

Complete reference for the Clowd Artifact Management API

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Or alternatively:

x-api-key: YOUR_API_KEY

Note: API access requires a Pro Max plan or higher. Generate your API key from your account settings.

Base URL

https://api.clowd.host/v1/

POST /artifacts

Create a new artifact with file upload. Supports multipart/form-data for file uploads.

Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Request Body (Form Data)

Parameter	Type	Required	Description
`file`	File	Yes	The file to upload (max 100MB)
`version_name`	String	Yes	Custom name for this version
`password`	String	No	Password protection (requires paid plan)
`allow_comments`	Boolean	No	Enable comments (default: true)
`allow_downloads`	Boolean	No	Enable downloads (default: true)
`view_only`	Boolean	No	View-only mode (default: false)
`expiration_date`	ISO 8601 Date	No	Expiration date (requires paid plan)

Response (201 Created)

{
  "status": true,
  "message": "Artifact created successfully",
  "slug": "abc123xyz"
}

Error Responses

400 Bad Request - Missing File

{
  "status": false,
  "message": "File is required"
}

403 Forbidden - Artifact Limit Reached

{
  "status": false,
  "message": "Artifact limit reached",
  "current": 50,
  "limit": 50
}

403 Forbidden - Storage Quota Exceeded

{
  "status": false,
  "message": "Storage quota exceeded",
  "current": 1024000,
  "limit": 1048576,
  "remaining": 24576
}

403 Forbidden - Feature Not Available

{
  "status": false,
  "message": "Password protection requires a paid plan. Upgrade to access this feature.",
  "feature": "passwordProtection"
}

cURL Example

curl -X POST https://clowd.host/api/v1/artifacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/file.pdf" \
  -F "version_name=Initial Release" \
  -F "allow_comments=true" \
  -F "allow_downloads=true"

GET /artifacts

Retrieve a paginated list of your artifacts with optional filtering and sorting.

Request Headers

Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Default	Description
`page`	Integer	1	Page number for pagination
`limit`	Integer	20	Number of items per page
`is_published`	Boolean	-	Filter by publish status
`sort_by`	String	created_at	Sort field: created_at, total_views, total_downloads, updated_at
`sort_order`	String	desc	Sort order: asc or desc

Response (200 OK)

{
  "status": true,
  "artifacts": [
    {
      "id": "uuid",
      "slug": "abc123xyz",
      "user_id": "user-uuid",
      "is_published": true,
      "allow_comments": true,
      "allow_downloads": true,
      "view_only": false,
      "total_views": 150,
      "total_downloads": 45,
      "total_comments": 3,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z",
      "current_version_number": 2,
      "current_version_name": "v2.0",
      "current_file_url": "https://...",
      "current_file_type": "application/pdf",
      "current_file_extension": "pdf"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

cURL Example

curl -X GET "https://clowd.host/api/v1/artifacts?page=1&limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT /artifacts/:slug

Update artifact metadata or create a new version by uploading a file. Supports both metadata-only updates and file uploads.

Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

URL Parameters

Parameter	Description
`slug`	The unique slug identifier of the artifact

Request Body (Form Data)

Parameter	Type	Description
`file`	File	Upload new file to create new version
`is_published`	Boolean	Publish/unpublish artifact
`password`	String	Set/update password (empty to remove)
`keep_password`	Boolean	Inherit password from previous version
`version_name`	String	Update version name
`allow_comments`	Boolean	Enable/disable comments
`allow_downloads`	Boolean	Enable/disable downloads
`view_only`	Boolean	Set view-only mode
`show_combined_comments`	Boolean	Show comments across all versions
`expiration_date`	ISO 8601 Date	Set/update expiration (null to remove)

Response (200 OK)

{
  "status": true,
  "message": "Artifact updated successfully",
  "version_number": 2,
  "password_inherited": false
}

Error Responses

404 Not Found

{
  "status": false,
  "message": "Artifact not found"
}

403 Forbidden - Unauthorized

{
  "status": false,
  "message": "Unauthorized to update this artifact"
}

cURL Examples

Metadata-only update:

curl -X PUT https://clowd.host/api/v1/artifacts/abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "is_published=true" \
  -F "allow_downloads=false"

Create new version with file:

curl -X PUT https://clowd.host/api/v1/artifacts/abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/updated-file.pdf" \
  -F "version_name=v2.0" \
  -F "keep_password=true"

DELETE /artifacts/:slug

Soft delete an artifact. The artifact is marked as deleted but data is preserved for potential recovery.

Request Headers

Authorization: Bearer YOUR_API_KEY

URL Parameters

Parameter	Description
`slug`	The unique slug identifier of the artifact to delete

Response (200 OK)

{
  "status": true,
  "message": "Artifact deleted successfully"
}

Error Responses

404 Not Found

{
  "status": false,
  "message": "Artifact not found"
}

403 Forbidden

{
  "status": false,
  "message": "Unauthorized to delete this artifact"
}

cURL Example

curl -X DELETE https://clowd.host/api/v1/artifacts/abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

API requests are subject to rate limiting based on your plan:

• Free Plan: Not available
• Pro Plan: Not available
• Pro Max Plan: 1000 requests/hour

Error Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions or plan limits
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Best Practices

• Secure your API key: Never expose your API key in client-side code or public repositories
• Handle errors gracefully: Always check the status field in responses and handle error cases
• Use pagination: When listing artifacts, use pagination to avoid large response payloads
• Monitor limits: Keep track of your artifact count, storage usage, and impression limits
• Version management: Use version_name to keep track of different versions of your artifacts
• File size optimization: Compress files before uploading to maximize your storage quota