Create Asset

API to upload an asset from a source URL to Connectly's CDN

Create Asset

Endpoint

POST /v1/businesses/{businessId}/assets

Path Parameters

Parameter	Type	Required	Description
businessId	string	Yes	Your business ID (UUID format)

Request Body

Field	Type	Required	Description
uri	string	Yes	Source URL of the asset to fetch and store
id	string	No	Optional custom asset ID. If not provided, a new UUID will be generated
metadata	object	No	Optional metadata for the asset
metadata.accessControlType	string	No	Access control setting (see Access Control Types below)

Access Control Types

Value	Description
ASSET_ACCESS_CONTROL_TYPE_PUBLIC	Asset is publicly accessible (default)
ASSET_ACCESS_CONTROL_TYPE_PRIVATE	Asset requires authentication to access
ASSET_ACCESS_CONTROL_TYPE_CDN_PRIVATE	Asset is accessible only via CDN

Response

Field	Type	Description
asset.id	string	Unique identifier for the asset
asset.ownerId	string	Business ID that owns the asset
asset.uri	string	CDN URL where the asset is accessible
asset.source.uri	string	Original source URL
asset.metadata.accessControlType	string	Access control setting

Examples

Basic Request

curl -X POST "https://api.connectly.ai/v1/businesses/550e8400-e29b-41d4-a716-446655440000/assets" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/images/product-photo.png"
  }'

Response:

{
  "asset": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "ownerId": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "https://cdn.connectly.ai/assets/6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "source": {
      "uri": "https://example.com/images/product-photo.png"
    },
    "metadata": {
      "accessControlType": "ASSET_ACCESS_CONTROL_TYPE_PUBLIC"
    }
  }
}

Request with Custom ID

curl -X POST "https://api.connectly.ai/v1/businesses/550e8400-e29b-41d4-a716-446655440000/assets" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/images/product-photo.png",
    "id": "product-sku-12345-main-image"
  }'

Request with Metadata

curl -X POST "https://api.connectly.ai/v1/businesses/550e8400-e29b-41d4-a716-446655440000/assets" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/documents/invoice.pdf",
    "metadata": {
      "accessControlType": "ASSET_ACCESS_CONTROL_TYPE_CDN_PRIVATE"
    }
  }'

Error Responses

Invalid Request (400)

{
  "code": 3,
  "message": "XASSET.INVALID_ARGUMENT: uri is required"
}

Authentication Error (401)

{
  "code": 16,
  "message": "XASSET.UNAUTHENTICATED: missing or invalid API key"
}

Source URL Unreachable (400)

{
  "code": 3,
  "message": "XASSET.INVALID_ARGUMENT: unable to fetch asset from source URI"
}

Rate Limiting

This endpoint is limited to 100 requests per second. If the limit is exceeded, the API will return a 429 Too Many Requests response.