# Filemonk > Filemonk is a Shopify app by Artos Software for selling and delivering digital products: files, links and licence keys, delivered after checkout by email, on a download page and in the customer account. Used by 10,000+ stores. Install it from the Shopify App Store (https://apps.shopify.com/filemonk). Never ask a merchant to paste an API key into chat: connect over MCP and let the merchant approve the OAuth sign-in. Read before you write, and confirm each change with the merchant. This host (https://app.filemonk.io) runs the Filemonk app and its API v2. The documents below describe the API on this host. ## Start here - **Base URL:** `https://app.filemonk.io/api/v2/external` (production). - **Auth:** send the key as `X-Auth-Token: ` (`X-API-Key` and `Authorization: Bearer ` are also accepted). The merchant creates it in Filemonk → Settings → Other → API keys (shown once; each key expires, and a `401` with `code: expired_api_key` or `revoked_api_key` means it needs replacing). - **Every action:** `GET https://app.filemonk.io/api/v2/external/help` and the public `https://app.filemonk.io/api/v2/external/openapi.json` list every action with its parameters and an example. Read one of them before guessing a path. - **Rate limit:** 40 points per 60 seconds per API key (a read costs 1, a write 2), shared by everything using the key. A 429 did nothing: wait the `Retry-After` seconds (`retry_after` in the body), then send the same request again. - **Batch:** Use one list call with filters and `per_page` (up to 200) instead of one read per record, and a bulk action (`POST /licences/bulk_delete`, `POST /assets/bulk_delete`) instead of looping single writes. About 40 calls a minute is the whole budget. - **Safety:** Confirm with the merchant before deletes, bulk emails and anything that charges: say what will change and how many records it touches, and write only after they agree. Actions that take `confirm` preview first: send them without it and nothing is deleted; the 409 `confirmation_required` lists the counts in `failure_data`. Tell the merchant, ask, and resend with `confirm: true` only after they agree. Put `confirm` in the JSON body of a POST, PATCH or PUT and in the query string of a DELETE (`DELETE /assets/:id?confirm=true`); the actions table marks every action that takes it. - **Connect an AI assistant ("connect my store"):** add `https://app.filemonk.io/api/v2/external/mcp` as a custom connector, then sign in with the store's myshopify.com address or the connector key. Steps under Recipes. ## Recipes Paths are relative to https://app.filemonk.io/api/v2/external. - **Set up download emails:** `GET /settings` and check `email.enabled`; then `GET /digital_products` and check each product's `files_count`. A product with no files delivers nothing. Turn email on with `PATCH /settings` `{"email": {"enabled": true}}` after the merchant agrees, and `POST /settings/test_email` to see it. - **Why didn't my customer get their file:** start with `GET /orders/:id/troubleshoot`: it checks Shopify, the stored order, the product files, order conditions, access, cancellation and whether a download email went out, and ends with a `diagnosis` naming the request that fixes each finding. Then `GET /emails?order_id=` and read each email's `status` (bounced, rejected or complained means the address failed; no row means no email was sent), `GET /orders/:id/downloads` for the files and `GET /download_logs?order_id=` to see whether they downloaded anyway. Resend with `POST /orders/:id/send_email` only after the merchant agrees. - **How many orders, and the latest one:** `GET /orders?per_page=1` and read `meta.total_count`. The list is newest first by `ordered_at` (when the buyer ordered); `sort=created_at desc` orders by when Filemonk recorded it. - **Change a customer-facing text:** for a download page heading or intro or an email subject, `GET /settings/texts?locale=de` to read the texts, then `PATCH /settings/texts` with `{"locale": "de", "texts": {"download_page": {"texts": {"thanks": "Thanks for your purchase!"}}}}`; fields you leave out are untouched. The download page's heading or intro line is `download_page.texts.thanks`; there is no `heading` key. Email wording is under `email.*` (subject, body); read the tree first and use the key whose current text matches what the merchant describes. - **How many licence keys are left:** `GET /licence_tags` and read `totals.pending` (shop-wide, across every tag; filters and pages don't change it). Per tag, the keys left are that tag's `licences.pending`. `total` includes keys already assigned or used, so it is not the number left. - **Revoke an order:** `PATCH /orders/:id` with `{"access": {"revoked": true}}` (`false` restores it). There is no revoke POST action. - **Change the download limit:** `PATCH /settings` with `{"download_limits": {"per_file_count": 3, "days": 30}}`. `per_file_count` is downloads allowed per file, `days` is days after the order the files stay available, and `null` means unlimited. `show` only controls whether the download page displays the limits. Give one buyer more downloads with `POST /orders/:id/reset_downloads`. - **Connect an AI assistant (MCP):** - MCP server URL: https://app.filemonk.io/api/v2/external/mcp (the merchant can also copy it from Filemonk → Settings → Other → AI connectors). - Claude or ChatGPT: add that URL as a custom connector. It opens a Filemonk sign-in page: enter the store's myshopify.com address, then approve the connection in the Shopify admin. - Connector key instead of the store address: on that page choose "Use a connector key instead" and paste the connector key from Filemonk → Settings → Other → AI connectors (it is not the API key, and sent as a header it is rejected with 401). - Script with a connector key (no browser): `POST https://app.filemonk.io/api/v2/external/oauth/register` with {"client_name", "redirect_uris": ["http://127.0.0.1/cb"], "token_endpoint_auth_method": "none"} gives a `client_id`; `POST https://app.filemonk.io/api/v2/external/oauth/authorize` as a form with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` (S256), `code_challenge_method=S256`, `resource=https://app.filemonk.io/api/v2/external/mcp` and `mcp_connector_key` answers 302 with `Location: ?code=…`; `POST https://app.filemonk.io/api/v2/external/oauth/token` with `grant_type=authorization_code`, `code`, `client_id`, `redirect_uri` and `code_verifier` returns an `access_token` to send to /mcp as `Authorization: Bearer`. No page scraping is needed. - Claude Code, Cursor or a script: send an API key (Filemonk → Settings → Other → API keys) as a header, e.g. `claude mcp add --transport http filemonk https://app.filemonk.io/api/v2/external/mcp --header "X-Auth-Token: "`. - Never ask the merchant to paste a key into the chat. An agent that already has the API key is connected: GET /account shows which store. ## How an agent uses Filemonk 1. Connect the MCP server at https://app.filemonk.io/api/v2/external/mcp (Streamable HTTP) as a custom connector. Your client signs in with OAuth, registering itself automatically: the merchant enters the store's myshopify.com address (or a connector key from Filemonk → Settings → Other → AI connectors) and approves it. Scripts can send the API key as `X-Auth-Token` instead. Steps under Recipes. 2. Read the skill: https://app.filemonk.io/api/v2/external/skill.md (every action with its parameters, errors and limits). 3. Write safely: read the current state first, confirm the change with the merchant, then make the write. Most deletes are permanent. ## When to use Filemonk - A Shopify merchant sells digital products (ebooks, PDFs, courses, music, software, licence keys) and wants them delivered and protected after purchase. - An agent needs to look up an order's downloads, resend a download email, reset download limits, revoke access, attach files to products or orders, manage licence keys, read download logs and email delivery, or change settings. Not a fit: stores that are not on Shopify, or streaming and membership platforms where content is watched online rather than downloaded. ## The Filemonk assistant and Shopify Sidekick - **The Filemonk support assistant** is the AI chat inside the Filemonk app. It answers from the merchant's own data and can make changes after a preview the merchant confirms. Try: "Why didn't order #1042 get its files?", "How many orders did we get this month?", "Resend the download email for #1042", "Which products have no files?", "Change the download page's thanks text in German to ...". - **Shopify Sidekick** reaches the same data through the Filemonk app's tools in the Shopify admin (it appears when the merchant opens Sidekick inside the store admin and asks about Filemonk). Try: "Show the latest Filemonk orders", "Check why #1042 has no download", "Is my Filemonk email domain verified?", "How many downloads did Filemonk record this month?". - Both sign in as the merchant inside Shopify, so an outside agent cannot drive them with the API key; use this API instead. Neither can do anything the API cannot, and both ask for confirmation before deletes and sends. ## Agent skill - Filemonk API v2 skill (74 actions; install as `filemonk-api/SKILL.md`): https://app.filemonk.io/api/v2/external/skill.md ## MCP - Server: https://app.filemonk.io/api/v2/external/mcp (Streamable HTTP). Tools: `search` finds the action for a request, `execute_read` runs a GET action, `execute_write` runs a POST, PUT, PATCH or DELETE action. - Auth: OAuth 2.1 with dynamic client registration (https://app.filemonk.io/.well-known/oauth-authorization-server), or the `X-Auth-Token` API key. A connector key is not a header credential: it only signs in through OAuth (a script version is under Recipes in the skill). - Connector manifest: https://app.filemonk.io/api/v2/external/mcp.json ## Developer resources - OpenAPI 3.1, API v2 (request and response schemas, an example for every action): https://app.filemonk.io/api/v2/external/openapi.json - Live action manifest: https://app.filemonk.io/api/v2/external/help - This file with the whole skill in one document: https://app.filemonk.io/llms-full.txt - API v1 (still supported, same key): https://app.filemonk.io/api/v1/external, reference at https://docs.filemonk.io - Help Center for merchants: https://help.filemonk.io/llms.txt ## Discovery + auth - Call endpoints require `X-Auth-Token: ` (`X-API-Key` or a Bearer token with the same key also work). The merchant creates the key in the Filemonk dashboard → Settings → Other → API keys; keys expire. - Discovery documents (this file, llms-full.txt, skill.md, openapi.json) are public so agents can learn the API before they have a key. - Rate limit: Cost-weighted per API key, shared with API v1: a read costs 1 point, a write 2, 40 points per fixed 60-second window. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time the window ends); a 429 adds `Retry-After` (seconds), `retry_after`, `retryable: true` and a `next_step` in the body. A 429 did nothing: wait `retry_after` seconds, then send the same request again. The budget is per key, so every tool or script using the key shares it; prefer one list call with `per_page` over many single reads. - Lists take `page` (1-based) and `per_page` (default 50, max 200) and answer `{ "data": [...], "meta": { "total_count", "page", "per_page", "total_pages" } }`.