## Create an asset upload

**post** `/assets`

Creates an asset from a source string. Pass source="signed-url" to reserve a direct upload URL, or pass an allowlisted HTTPS URL for server-side fetch. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Body Parameters

- `source: string`

  Asset source as a string: either "signed-url" to reserve a direct upload URL, or an allowlisted HTTPS URL for server-side fetch.

- `workspace_id: string`

  Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_.

- `content_type: optional string`

  Asset content type

- `file_name: optional string`

  Asset file name

- `folder: optional string`

  Destination folder

### Returns

- `asset_id: string`

  Asset identifier

- `status: "pending_upload" or "ready" or "failed"`

  - `"pending_upload"`

  - `"ready"`

  - `"failed"`

- `uploaded_via: "url" or "signed_url"`

  Asset source

  - `"url"`

  - `"signed_url"`

- `url: string`

  Asset URL

- `visibility: "workspace"`

  - `"workspace"`

- `workspace_id: string`

  Workspace identifier

- `expires_at: optional string`

  Expiration time for the upload URL

- `upload: optional object { content_type, file_field, form_fields, 2 more }`

  - `content_type: "multipart/form-data"`

    - `"multipart/form-data"`

  - `file_field: "file"`

    - `"file"`

  - `form_fields: map[string]`

    Upload form fields

  - `method: "POST"`

    - `"POST"`

  - `url: string`

    Upload URL

- `upload_url: optional string`

  Upload URL (serialized)

### Example

```http
curl https://app.flora.ai/api/v1/assets \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FLORA_API_KEY" \
    -d '{
          "source": "signed-url",
          "workspace_id": "ws_abc123"
        }'
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "status": "pending_upload",
  "uploaded_via": "url",
  "url": "https://example.com",
  "visibility": "workspace",
  "workspace_id": "ws_abc123",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "upload": {
    "content_type": "multipart/form-data",
    "file_field": "file",
    "form_fields": {
      "foo": "string"
    },
    "method": "POST",
    "url": "https://example.com"
  },
  "upload_url": "https://upload.imagekit.io/api/v1/files/upload"
}
```