# Create Asset

## 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

```bash
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:**

```json
{
  "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

```bash
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

```bash
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)

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

#### Authentication Error (401)

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

#### Source URL Unreachable (400)

```json
{
  "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.