---
title: "Insert a file attachment"
method: POST
path: "/public/v1/file-attachments"
tags: ["FileAttachment"]
---

# Insert a file attachment

`POST /public/v1/file-attachments`

Uploads a file and attaches it to exactly one existing record. On success the file is stored and
served back through the `url` on the response, so a single call both persists the document and
makes it downloadable.

Send the request as `multipart/form-data` with three parts:
• `file` — the binary to upload. Required, and must be non-empty (a zero-byte file is rejected).
• `name` — optional display name; defaults to the uploaded file's original filename when omitted or blank.
• exactly one reference id (`product_id`, `order_id`, `purchase_id`, ...) naming the record to attach to. Supply the id — the same id that record's own endpoint returns. Providing no reference id is rejected, and providing more than one is also rejected; exactly one is required.

This endpoint is create-only. There is no public endpoint to update or delete an attachment, and a
file cannot be replaced once uploaded — upload a new attachment instead. The response echoes the
attachment with all reference-id fields present but only the one you set populated; the rest are null.

The attachment is owned by the company tied to the API key you authenticate with, and the response's
`uploader` is the user that key belongs to. On success you get a 201 with the created attachment
wrapped in a `data` envelope; its `url` is immediately downloadable.

System effects: the upload counts against your company's storage quota. If it would exceed the
remaining quota the call fails with 400 and nothing is stored — free space under Settings (or remove
other attachments) and retry. This endpoint does not move inventory and does not push to Metrc or
BioTrack; it only associates a document with the referenced record.

Required permission: `products_permissions_edit`.

## Response `201`

File attachment inserted successfully

## Other responses

- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/eb775b7b6ee0/schema)