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

# Create Asset

> Create an internal, external URL, or licence key asset.

For `internal` assets the asset row and a presigned upload URL are returned in
a single call. See [Upload Asset](./upload-asset) for a walk-through of
uploading the file body.

<Note>
  The `internal` asset type is in **beta**. The request and response shapes are
  stable for production use, but we may add new fields or capabilities without
  notice. See [Upload Asset](./upload-asset) for details.
</Note>

## Request body

<ParamField body="asset" type="object" required>
  <Expandable title="Asset fields">
    <ParamField body="type" type="string" required>
      The asset type. Accepted values: `internal`, `external`, `licence`.

      * `internal` — a file stored in Filemonk storage. The response includes a
        presigned URL for uploading the file body.
      * `external` — a file hosted at an external URL.
      * `licence` — a licence key asset (assigned to customers on purchase).
    </ParamField>

    <ParamField body="filename" type="string">
      Required when `type` is `internal`. Used as the suggested attachment name
      on download.
    </ParamField>

    <ParamField body="byte_size" type="integer">
      Required when `type` is `internal`. Size of the file in bytes. Must be
      positive and at most 2 GB.
    </ParamField>

    <ParamField body="content_type" type="string">
      Optional MIME type for `internal` assets. Defaults to
      `application/octet-stream`.
    </ParamField>

    <ParamField body="external_url" type="string">
      The URL of the file. Required when `type` is `external`.
    </ParamField>

    <ParamField body="name" type="string">
      A display name for the asset. Particularly useful for `licence` type
      assets which have no filename.
    </ParamField>

    <ParamField body="watermark_asset" type="boolean" default="false">
      Whether to apply PDF watermarking to this asset when it is delivered to
      customers. Watermarking must also be enabled in your store settings.
    </ParamField>

    <ParamField body="autogenerate_licence_key" type="boolean" default="false">
      When `true`, a unique licence key is automatically generated and assigned
      to the customer when they purchase a product containing this asset. Only
      applies to `licence` type assets.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="asset" type="object" required>
  The newly created asset.
</ResponseField>

<ResponseField name="upload" type="object">
  Only present when `type` is `internal`. A single-PUT handle
  (`method: "PUT"`) with the presigned URL and headers required to upload the
  file body. See [Upload Asset](./upload-asset) for the field-by-field
  breakdown.
</ResponseField>

<RequestExample>
  ```bash cURL (internal) theme={null}
  curl -X POST 'https://app.filemonk.io/api/v1/external/assets' \
    -H 'X-Auth-Token: fm_api_key_your_key_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "asset": {
        "type": "internal",
        "filename": "brushes-pack-v2.zip",
        "byte_size": 1048576,
        "content_type": "application/zip",
        "name": "Photoshop Brushes Pack"
      }
    }'
  ```

  ```bash cURL (external) theme={null}
  curl -X POST 'https://app.filemonk.io/api/v1/external/assets' \
    -H 'X-Auth-Token: fm_api_key_your_key_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "asset": {
        "type": "external",
        "external_url": "https://cdn.example.com/files/brushes-pack-v2.zip",
        "name": "Photoshop Brushes Pack"
      }
    }'
  ```

  ```bash cURL (licence key) theme={null}
  curl -X POST 'https://app.filemonk.io/api/v1/external/assets' \
    -H 'X-Auth-Token: fm_api_key_your_key_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "asset": {
        "type": "licence",
        "name": "Software Licence",
        "autogenerate_licence_key": true
      }
    }'
  ```

  ```javascript Node.js (internal) theme={null}
  const create = await fetch(
    'https://app.filemonk.io/api/v1/external/assets',
    {
      method: 'POST',
      headers: {
        'X-Auth-Token': 'fm_api_key_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        asset: {
          type: 'internal',
          filename: 'brushes-pack-v2.zip',
          byte_size: fileBuffer.byteLength,
          content_type: 'application/zip'
        }
      })
    }
  ).then(r => r.json());

  await fetch(create.upload.url, {
    method: 'PUT',
    headers: create.upload.headers,
    body: fileBuffer
  });
  ```

  ```python Python (internal) theme={null}
  import requests

  create = requests.post(
      'https://app.filemonk.io/api/v1/external/assets',
      headers={'X-Auth-Token': 'fm_api_key_your_key_here'},
      json={
          'asset': {
              'type': 'internal',
              'filename': 'brushes-pack-v2.zip',
              'byte_size': len(file_bytes),
              'content_type': 'application/zip'
          }
      }
  ).json()

  requests.put(
      create['upload']['url'],
      headers=create['upload']['headers'],
      data=file_bytes
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 (internal) theme={null}
  {
    "asset": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "internal",
      "name": "Photoshop Brushes Pack",
      "filename": "brushes-pack-v2.zip",
      "content_type": "application/zip",
      "byte_size": 1048576,
      "watermark_asset": false,
      "autogenerate_licence_key": false,
      "created_at": "2026-04-08T10:00:00Z",
      "updated_at": "2026-04-08T10:00:00Z"
    },
    "upload": {
      "method": "PUT",
      "url": "https://<bucket>.r2.cloudflarestorage.com/external_api/<shop_id>/8f3a.zip?X-Amz-Signature=...",
      "headers": {
        "Content-Type": "application/zip",
        "Content-Disposition": "inline; filename=\"brushes-pack-v2.zip\""
      },
      "expires_at": "2026-04-08T11:00:00Z"
    }
  }
  ```

  ```json 201 (external) theme={null}
  {
    "asset": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "external",
      "name": "Photoshop Brushes Pack",
      "filename": "brushes-pack-v2.zip",
      "external_url": "https://cdn.example.com/files/brushes-pack-v2.zip",
      "content_type": "application/zip",
      "byte_size": 0,
      "watermark_asset": false,
      "autogenerate_licence_key": false,
      "created_at": "2026-04-08T10:00:00Z",
      "updated_at": "2026-04-08T10:00:00Z"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "errors": ["External url can't be blank"]
  }
  ```
</ResponseExample>