# Create a media asset from URL

_NgCms / Media Assets_

`POST /ng-cms/media/{projectId}/from-url`

## Parameters

- `projectId` (string, required) — The unique identifier of the project (bucket)

## Request Body

### `CreateMediaFromUrlRequest`

- `url` (string, required) — Publicly accessible URL of the remote asset to register or download
- `title` (string, optional) — Human-readable title for the asset. Defaults to the filename extracted from the URL if omitted.
- `description` (string, optional) — Optional description of the media asset.
- `upload` (boolean, optional) — If true, the file is downloaded from the URL and uploaded to storage (S3). If false (default), the URL is stored as-is without downloading.

## Responses

### `201` — Media asset created successfully. Returns the new asset ID.

Type: `ApiResponse<string>`

- `success` (boolean) — Always true on success
- `result` (string) — The ID of the newly created media asset
- `errors` (ErrorDetail[]) — List of errors (empty on success)

### `400` — Bad Request. No URL was provided, or when upload=true the remote URL returned a non-success HTTP status.


### `401` — Unauthorized. A valid bearer token is required.


### `412` — Precondition Failed. The project's current plan does not allow access to this resource, or payment is required to proceed.


### `500` — Unexpected server error.

Type: `ApiResponse<T>`

- `success` (boolean) — Always false
- `errors` (ErrorDetail[]) — List of server-side errors
  - `correlationId` (string) — Unique ID for tracing the error
  - `message` (string) — Error message
  - `stack` (string) — Stack trace (non-production only)


## Code Examples

### curl

```curl
curl --request POST \
  --url https://apis-spb.konso.io/ng-cms/media/{projectId}/from-url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/hero.jpg",
  "title": "Hero Image",
  "upload": true
}'
```

### javascript

```js
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/hero.jpg',
    title: 'Hero Image',
    upload: true
  })
};

fetch('https://apis-spb.konso.io/ng-cms/media/{projectId}/from-url', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

### dotnet

```dotnet
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "<token>");

var request = new CreateMediaFromUrlRequest
{
    Url = "https://example.com/hero.jpg",
    Title = "Hero Image",
    Upload = true
};

var response = await client.PostAsJsonAsync("https://apis-spb.konso.io/ng-cms/media/{projectId}/from-url", request);
var result = await response.Content.ReadFromJsonAsync<ApiResponse<string>>();
```

### python

```python
import requests

url = "https://apis-spb.konso.io/ng-cms/media/{projectId}/from-url"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://example.com/hero.jpg",
    "title": "Hero Image",
    "upload": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Request Body Example

```json
{
  "projectId": "example-string"
}
```

### Response Example (201)

```json
{
  "success": true,
  "result": "ma_a1b2c3d4e5f6",
  "errors": []
}
```