> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Asset

> Upload a media file to Connectly's CDN by providing a source URL. Returns a stable CDN URL for use in templates and messages 🎧

Upload a media file to Connectly's CDN by providing a publicly accessible source URL. Connectly fetches the file from your URL and stores it, returning a stable CDN URL you can reference in templates, campaigns, and messages.

## Endpoint

```json theme={null}
POST https://api.connectly.ai/v1/businesses/{businessId}/assets
```

**Rate limit:** 100 requests/second. Exceeding this returns `429 Too Many Requests`.

## Request body

<ParamField body="uri" type="string" required>
  Publicly accessible source URL of the file to upload. Must be reachable from Connectly's servers — private or authenticated URLs will fail with a `400` error.
</ParamField>

<ParamField body="id" type="string">
  Optional custom identifier for the asset. If omitted, Connectly generates a UUID automatically. Useful for associating assets with your own records (e.g. a product SKU or internal asset key).
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata to attach to the asset.

  <Expandable title="metadata fields">
    <ParamField body="metadata.accessControlType" type="string">
      Controls who can access the stored asset. Defaults to `ASSET_ACCESS_CONTROL_TYPE_PUBLIC`.

      | Value                                   | Description                                           |
      | --------------------------------------- | ----------------------------------------------------- |
      | `ASSET_ACCESS_CONTROL_TYPE_PUBLIC`      | Publicly accessible without authentication (default). |
      | `ASSET_ACCESS_CONTROL_TYPE_PRIVATE`     | Requires authentication to access.                    |
      | `ASSET_ACCESS_CONTROL_TYPE_CDN_PRIVATE` | Accessible only via Connectly's CDN.                  |
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="asset" type="object">
  <Expandable title="asset fields">
    <ResponseField name="asset.id" type="string">
      Unique identifier for the asset — either your custom `id` or a generated UUID.
    </ResponseField>

    <ResponseField name="asset.ownerId" type="string">
      The business ID that owns this asset.
    </ResponseField>

    <ResponseField name="asset.uri" type="string">
      The Connectly CDN URL where the asset is now hosted. Use this when referencing the asset in templates or messages.
    </ResponseField>

    <ResponseField name="asset.source.uri" type="string">
      The original source URL you provided in the request.
    </ResponseField>

    <ResponseField name="asset.metadata.accessControlType" type="string">
      The access control setting applied to this asset.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<AccordionGroup>
  <Accordion title="Basic upload">
    ```bash theme={null}
    curl -X POST "https://api.connectly.ai/v1/businesses/{businessId}/assets" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "uri": "https://example.com/images/product-photo.png" }'
    ```

    ```json theme={null}
    {
      "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" }
      }
    }
    ```
  </Accordion>

  <Accordion title="Upload with a custom ID">
    ```bash theme={null}
    curl -X POST "https://api.connectly.ai/v1/businesses/{businessId}/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"
      }'
    ```
  </Accordion>

  <Accordion title="Upload with access control">
    ```bash theme={null}
    curl -X POST "https://api.connectly.ai/v1/businesses/{businessId}/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" }
      }'
    ```
  </Accordion>
</AccordionGroup>

## Error responses

| Status | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `400`  | Missing or invalid `uri`, or source URL unreachable by Connectly's servers. |
| `401`  | Missing or invalid `X-API-Key`.                                             |
| `429`  | Rate limit exceeded (100 req/s).                                            |