# Datasheet uploads

How your agent keeps a datasheet PDF with a device - from a public URL, or from your computer by a one-time upload link - and what each answer means.

Source: https://rack-maker.cbnsndwch.dev/docs/agents/datasheet-uploads

## Two ways to keep a datasheet

Your agent can keep a private copy of a device's datasheet with its draft, as **Keep a private copy** does in the modeler's datasheet panel:

- **From a public URL:** `attach_datasheet` with the PDF's http(s) URL. The server fetches it.
- **From your computer:** `create_datasheet_upload` gives a one-time link, and the agent uploads the file to it with a shell command.

Either way, the copy is private: only you and Rack Maker's admins can open it, and the device's public page shows only its datasheet link. It shows under **Kept copies** in the modeler. See [Datasheets](https://rack-maker.cbnsndwch.dev/docs/modeler/datasheets).

The agent still reads the PDF itself for the numbers. Keeping a copy is for you, to open again later.

![The datasheet panel in the modeler, with the kept private copy of a datasheet listed under Kept copies](https://rack-maker.cbnsndwch.dev/docs/shots/modeler/datasheet-light.webp)

*A kept copy shows under Kept copies in the modeler.*

> **Only datasheets, never photos:**
>
> An upload link is the only way a file reaches Rack Maker from your agent, and it takes only a PDF. Photos are never
> uploaded: the agent reads them on your computer and sends numbers.

## From a public URL

`attach_datasheet` takes the draft and the PDF's public http(s) URL, and optionally a file name to show.

- The PDF must be at most 15 MB.
- If the device has no datasheet link yet, it gets this URL.
- Where the copy came from is kept with it, and the modeler shows it ("from" and the site's name).
- The same URL attached again to the same device is the same copy: it isn't fetched again.

## From your computer

A tool call can't carry a file, so the agent asks for a link and sends the file itself.

1. The agent calls `create_datasheet_upload` with the draft and the file's name. The answer has the link and when it expires.
2. It uploads the PDF to the link with `curl`:

```bash
curl -sS -T ~/Downloads/nas-box.pdf https://rack-maker.cbnsndwch.dev/mcp/upload/<token>
```

`curl -T` sends a PUT. A POST of the file as the body works too:

```bash
curl -sS --data-binary @nas-box.pdf https://rack-maker.cbnsndwch.dev/mcp/upload/<token>
```

### The link

- **One-time:** it works once.
- **10 minutes:** it expires 10 minutes after it was made.
- **PDF only:** the file must start like a PDF. This is checked before the link is used up, so sending the wrong file doesn't waste it.
- **Up to 15 MB.**
- **Bound to you and the draft:** the link itself is the permission, so it needs no sign-in header, and the file is always kept with the draft it was made for, as yours, whatever the request says. Treat it like a password until it is used.
- **Limits:** 30 links per user an hour, and 30 upload attempts from one address in 10 minutes.

### The answers

The link answers in JSON, with an `error` explaining any refusal.

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| 201    | Kept. The answer names the draft and the kept copy.                                          |
| 200    | This file (same name and size) was already kept with the device. The kept copy is unchanged. |
| 400    | The PDF is missing: send it as the body.                                                     |
| 404    | No such link: it expired, was used, or never existed. Ask for another.                       |
| 405    | Wrong method: send the file with PUT (`curl -T`) or POST.                                    |
| 410    | This link was used already. Ask for another.                                                 |
| 411    | The file's length is missing. `curl -T` sends it.                                            |
| 413    | Over 15 MB.                                                                                  |
| 415    | Not a PDF (it doesn't start with `%PDF-`). The link still works: send the right file.        |
| 429    | Too many uploads from this address. Wait a few minutes.                                      |

Any other refusal comes from keeping the file (for example, more than 30 datasheets in an hour). The link is used up by then, so the agent asks for another.