# Drive API

Storing, reading and sharing files on the account's drive. The steps are in the Drive and share links guide.

## Drive

```bash
curl -X POST https://api.getstack.run/v1/drive/files \
  -H "Authorization: Bearer <access token>" -H "X-Passport-Token: $PASSPORT" -H "Content-Type: application/json" \
  -d '{"name":"report.txt","content_type":"text/plain","content_text":"Q3 numbers","visibility":"account"}'
```

- POST /v1/drive/files - { name, content_type?, content_text | content_base64, visibility? agent | account, expires_in_seconds? }. Returns 201 with the file; 10 MB at most. An agent's file is private to it unless visibility is account; the owner's upload is always the account's.
- PUT /v1/drive/files?name=&content_type=&visibility=&expires_in_seconds= - the whole file as the raw request body, up to 1 GB (a file typed as text, Markdown, CSV or JSON is 10 MB at most). name is required; the request's own Content-Type is ignored, and content_type is only the label the file carries (any media type; application/octet-stream when left out): the drive takes a file of any type and does not check the bytes against it. Send Content-Length when you know it, so a file that is too large is refused before it is read. The API streams the body and computes the SHA-256 itself: there is no hash, size, part or second call. Returns 201 with the file.
- POST /v1/drive/uploads - { name, content_type?, size_bytes?, visibility?, expires_in_seconds? }. For an agent that cannot stream a body itself. Counts one action. Returns 201 with a one-time upload link: id, url, method (PUT), name, content_type, max_bytes and expires_at. Run curl -T ./file '\<url>' with no Authorization header; the PUT's answer (201) is the file. The URL works once and lasts 30 minutes, and a failed attempt gives it back. The answer is never cached.
- GET /v1/drive/files - the files the caller may see, newest first, with the account's usage and limits: files, bytes (the files and the messages together), message_bytes, free_bytes, max_file_bytes, overage_bytes, download_bytes_month, download_free_bytes, links_paused and storage_unpaid (null in good standing, otherwise since, delete_on and over_bytes).
- GET /v1/drive/files/:id and GET /v1/drive/files/:id/content - the file's facts, and its content inline for a file up to 256 KB.
- PATCH /v1/drive/files/:id - { visibility?, expires_in_seconds? }. DELETE /v1/drive/files/:id removes the file and its bytes. Only the writer or the owner. A file that arrived with an email, or a result the MCP server handed off, changes like any file: its end can be moved or removed.
- POST /v1/drive/files/:id/copy - { name?, visibility?, expires_in_seconds? }. Returns 201 with a new file of the caller's own, with its own id, copied from a file the caller can see. It never ends unless expires_in_seconds is given. Counts as an upload: one action, put to your controls, and DRIVE_READ_ONLY while the drive is read-only.
- POST /v1/drive/files/:id/links - { ttl_seconds?, max_downloads? }. Returns a signed link, once. GET /v1/drive/files/:id/links lists them without their URLs; DELETE /v1/drive/files/:id/links/:linkId ends one.
- GET /v1/drive/links/:token - the download, with no credential: the signed token in the path is the credential.
- POST /v1/public/drive-reports { url, category, description, reporter_email? } - report a shared file by its link. Anyone may, with no credential.

A drive holds an account's files on STACK's storage, encrypted. Limits per account: 1 GB a file (10 MB for a file typed as text, Markdown, CSV or JSON), and any number of files. The first 25 GiB of storage and 5 GiB of share-link downloads a month are free; past them storage and downloads are charged at cost from the wallet, never on credit. A file of any type is taken and stored as it is (a 3D model, a Word, Excel or PowerPoint file, a program); its type is only a label. A download and a share link are always sent as an opaque attachment (`application/octet-stream`, with the type as a label in `X-Stack-Content-Type`), never shown as a page, so a link cannot host a web page, a script or a service worker. An inline read returns text (UTF-8 or UTF-16) as text, whatever the label, and anything else as base64. An upload and a share link are actions on the meter and are put to the account's controls (`drive.upload`, `drive.share`; a copy is an upload); reading, listing, changing and deleting are free. A file received with an email counts toward the storage like any file and is charged like one; it has no end of its own and goes with its message unless its end is changed. Every upload is in the signed record with the file's hash. A link lasts 15 minutes unless it says otherwise (any time from a minute), never past the file, and stops after the downloads it names (any number from one; 100 when it names none). A download spike pauses the account's share links and tells STACK; `links_paused` in the usage says so. If the wallet cannot pay for the storage past the free 25 GiB, the drive is read-only from that day: uploads, edits and new share links are refused (`DRIVE_READ_ONLY`), while reading, downloading, listing and deleting still work and existing share links keep working. The owner is emailed on day 0, day 30 and day 60, and on day 90 the newest files past the first 25 GiB are deleted (the oldest 25 GiB stay). Topping up the wallet to cover what is due, or deleting files until the drive is within 25 GiB, lifts the read-only state at once and cancels the countdown; `storage_unpaid` in the usage shows it. Five uploads of an account run at once. A file is untrusted content: it is marked so, scanned when an agent reads it, and what it carried from the sources its writer read follows it. A drop-off can hand a file to another agent: deposit with `drive_files`, and the collector's collect returns them.

- 413 DRIVE_FILE_TOO_LARGE - over the file size.
- 402 INSUFFICIENT_BALANCE - an upload would take the drive past 25 GiB and the wallet does not hold 30 days of the overage.
- 409 DRIVE_LINKS_PAUSED - STACK has paused the account's share links; none can be made.
- 409 DRIVE_READ_ONLY - the wallet could not pay for storage past the free 25 GiB: nothing is uploaded, changed or newly shared until it is paid or the drive is deleted down to within 25 GiB.
- 429 DRIVE_TOO_MANY_UPLOADS - the account already has 5 uploads running; try again when one has finished.
- 400 DRIVE_UPLOAD_ABORTED - the connection broke before the whole file arrived; nothing was stored. 408 DRIVE_UPLOAD_TIMED_OUT - the upload sent no byte for 5 minutes, or ran for more than 6 hours; nothing was stored.
- 404 DRIVE_UPLOAD_LINK_INVALID - the upload URL is forged, expired, already used or another account's.
- 400 DRIVE_FILE_EMPTY - the file has no bytes.
- 404 DRIVE_LINK_INVALID - the link is forged, ended, revoked, used up or its file is gone.
