Create Asset

For internal assets the asset row and a presigned upload URL are returned in a single call. See 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 for details.

Request body

• asset (object, required)

  Asset fields:

  • 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).

  • filename (string)

    Required when type is internal. Used as the suggested attachment name on download.

  • byte_size (integer)

    Required when type is internal. Size of the file in bytes. Must be positive and at most 2 GB.

  • content_type (string)

    Optional MIME type for internal assets. Defaults to application/octet-stream.

  • external_url (string)

    The URL of the file. Required when type is external.

  • name (string)

    A display name for the asset. Particularly useful for licence type assets which have no filename.

  • watermark_asset (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.

  • autogenerate_licence_key (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.

Response

• asset (object, required)

  The newly created asset.

• upload (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 for the field-by-field breakdown.

Example request

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"
    }
  }'

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"
    }
  }'

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
    }
  }'

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
});

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
)

Example response

{
  "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"
  }
}

{
  "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"
  }
}

{
  "errors": ["External url can't be blank"]
}