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

# Introduction

> Programmatically manage digital products, assets, and orders for your Shopify store through the Filemonk API.

The Filemonk API lets you manage your digital products and assets programmatically. Create and organize assets, link them to Shopify products as digital products, and query orders and download data — all through a simple REST API. Use it to automate your catalog, build custom integrations, sync data with external systems, or power your own workflows.

## What you can do

<CardGroup cols={2}>
  <Card title="Manage assets" icon="file" href="/api-reference/assets/list-assets">
    Create, list, update, and delete assets — uploaded files, external URLs, and licence keys that are delivered to customers.
  </Card>

  <Card title="Manage digital products" icon="box" href="/api-reference/digital-products/list-digital-products">
    Link assets to Shopify products and variants, configure preorders, and manage your digital catalog.
  </Card>

  <Card title="List orders" icon="list" href="/api-reference/orders/list-orders">
    Search and filter orders by name, email, status, or date range with full pagination support.
  </Card>

  <Card title="Get order downloads" icon="download" href="/api-reference/orders/get-order-downloads">
    Retrieve a flat list of all files for an order with pre-computed status flags — no filtering logic needed on your end.
  </Card>
</CardGroup>

## Base URL

All API requests are made to:

```
https://app.filemonk.io/api/v1/external
```

## Quick start

<Steps>
  <Step title="Get your API key">
    Open the Filemonk app in your Shopify admin and navigate to **Settings > Other > API**. Copy the API key displayed there.

    <Warning>
      Keep your API key secret. Anyone with this key can read and modify your store's digital products, assets, and order data.
    </Warning>
  </Step>

  <Step title="Create an asset">
    Assets are the files or licence keys that customers receive when they purchase a product. Start by creating one:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://app.filemonk.io/api/v1/external/assets' \
        -H 'X-Auth-Token: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "asset": {
            "type": "external",
            "external_url": "https://cdn.example.com/files/ebook-v2.pdf",
            "name": "Premium eBook"
          }
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://app.filemonk.io/api/v1/external/assets', {
        method: 'POST',
        headers: {
          'X-Auth-Token': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          asset: {
            type: 'external',
            external_url: 'https://cdn.example.com/files/ebook-v2.pdf',
            name: 'Premium eBook'
          }
        })
      });
      const data = await response.json();
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          'https://app.filemonk.io/api/v1/external/assets',
          headers={'X-Auth-Token': 'YOUR_API_KEY'},
          json={
              'asset': {
                  'type': 'external',
                  'external_url': 'https://cdn.example.com/files/ebook-v2.pdf',
                  'name': 'Premium eBook'
              }
          }
      )
      data = response.json()
      ```
    </CodeGroup>

    The response includes the asset's `id` — save this for the next step:

    ```json theme={null}
    {
      "asset": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "external",
        "name": "Premium eBook",
        "filename": "ebook-v2.pdf",
        "external_url": "https://cdn.example.com/files/ebook-v2.pdf",
        ...
      }
    }
    ```
  </Step>

  <Step title="Create a digital product">
    Link the asset to a Shopify product so customers receive it on purchase:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://app.filemonk.io/api/v1/external/digital_products' \
        -H 'X-Auth-Token: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "digital_product": {
            "shopify_product_id": 8847261098265,
            "asset_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
            "custom_message": "Thanks for your purchase!"
          }
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://app.filemonk.io/api/v1/external/digital_products', {
        method: 'POST',
        headers: {
          'X-Auth-Token': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          digital_product: {
            shopify_product_id: 8847261098265,
            asset_ids: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
            custom_message: 'Thanks for your purchase!'
          }
        })
      });
      const data = await response.json();
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          'https://app.filemonk.io/api/v1/external/digital_products',
          headers={'X-Auth-Token': 'YOUR_API_KEY'},
          json={
              'digital_product': {
                  'shopify_product_id': 8847261098265,
                  'asset_ids': ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
                  'custom_message': 'Thanks for your purchase!'
              }
          }
      )
      data = response.json()
      ```
    </CodeGroup>

    That's it — the Shopify product is now a digital product. When a customer purchases it, Filemonk will deliver the linked asset automatically.
  </Step>

  <Step title="Verify with a list request">
    Confirm everything is set up by listing your digital products:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET 'https://app.filemonk.io/api/v1/external/digital_products' \
        -H 'X-Auth-Token: YOUR_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://app.filemonk.io/api/v1/external/digital_products', {
        headers: { 'X-Auth-Token': 'YOUR_API_KEY' }
      });
      const data = await response.json();
      ```

      ```python Python theme={null}
      import requests

      response = requests.get(
          'https://app.filemonk.io/api/v1/external/digital_products',
          headers={'X-Auth-Token': 'YOUR_API_KEY'}
      )
      data = response.json()
      ```
    </CodeGroup>
  </Step>
</Steps>

## Typical workflow

The API is designed around two core resources: **assets** and **digital products**.

1. **Create assets** — Upload files directly, register external URLs, or generate licence keys via `POST /assets`. See [Upload Asset](/api-reference/assets/upload-asset) for the direct-upload flow.
2. **Create digital products** — Link assets to Shopify products via `POST /digital_products`, providing the `asset_ids` from step 1 and the `shopify_product_id` you want to attach them to.
3. **Manage and iterate** — Update assets or digital products as needed. You can add or remove assets from a digital product, change preorder settings, or swap out files.
4. **Query orders** — Use `GET /orders` and `GET /orders/{id}/downloads` to monitor purchases and download activity.

## Key concepts

### Assets vs digital products

An **asset** is a deliverable file or licence key — the thing customers actually receive. A **digital product** is the link between one or more assets and a Shopify product (or variant). You create assets first, then bundle them into digital products.

### Pre-computed download status

The downloads endpoint returns a flat array of files with all business logic already resolved. Each download object includes boolean flags like `download_expired`, `download_limit_reached`, `access_revoked`, and a master `downloadable` flag. You do not need to implement any expiration or limit checking on your side.

### Pagination

All list endpoints return paginated results. Use the `page` and `per_page` query parameters to navigate through results. The response includes a `pagination` object with `total_count` and `total_pages` for building pagination controls.

### Rate limiting

The API uses a token-bucket rate limiter. Every response includes `X-RateLimit-*` headers so you can track your usage. See [Rate Limiting](/rate-limiting) for details.