API reference
Auth
If you are an agent, the llms.txt quickstart covers this page in machine-readable form.
Every request carries your API key in a header:
Authorization: Bearer vlf_...
Keys start with vlf_ and are shown once at creation. Keep the key in an environment variable (VEILFILE_API_KEY) or a secret manager. Never put it in a prompt, a chat message, or a repo.
The veilfile command-line client gets you a key without pasting secrets. Install it with pip install veilfile, run veilfile login to approve in your browser, and use veilfile logout to revoke the key and veilfile status to check it. The full reference is in the API docs source.
Upload
POST /api/v1/artifacts
Multipart form:
| Field | Required | Notes |
|---|---|---|
file |
yes | Send the file bytes. The maximum size is 25 MiB. |
ttl_days |
no | Set the number of whole days until expiry. The default is the plan max. Larger values are clamped to the plan max; a non-integer gets 400 invalid_request. |
on_secret |
no | flag (default) or reject. reject refuses a file that trips the secret scanner (400 secret_detected) and stores nothing. |
visibility |
no | For a team, only_me or team, case-insensitive: who on the team can see the file on their Files page. It is honored only when the administrator lets each person decide; otherwise the team's setting applies. The answer's visibility says which one the file got, and any other value returns 400 invalid_request. |
The allowed file types are png, jpg, jpeg, webp, gif, txt, md, log, json, har, and pdf.
curl -X POST https://veilfile.com/api/v1/artifacts \
-H "Authorization: Bearer $VEILFILE_API_KEY" \
-F "file=@screenshot.png" \
-F "ttl_days=7"
A 201 comes back:
{
"id": "b3f7c2a1-...",
"url": "https://veilfile.com/a/4fK9vX2qZt8sW...",
"expires_at": "2026-10-12T00:25:00Z",
"size_bytes": 184320,
"secret_flags": []
}
ttl_adjusted: true appears when your ttl_days was clamped to the plan max. A warning string appears when secret_flags is non-empty. It reads: "The scan flagged this file as possibly containing a secret; see secret_flags. Ask the user whether to keep or revoke the file before sharing its link."
List
GET /api/v1/artifacts
The endpoint returns your workspace's artifacts, newest first, as a bare JSON array of {id, filename, mime_type, size_bytes, url, expires_at, secret_flags, created_at}. Optional limit (1 to 200) and cursor page through it; when more remain the response has X-Next-Cursor and Link: rel="next" headers.
Revoke
DELETE /api/v1/artifacts/<id>
The endpoint deletes the artifact at once. Its URL returns 404 immediately. Success is a 204 with an empty body. Unknown ids return 404 with {"error": "No file with that id exists in this workspace. Check the id.", "code": "not_found"}.
A file that staff hold is not revoked: the answer is 403 with {"error": "This file is held, so it was not revoked.", "code": "file_held"}.
Download
GET /a/<token>
This endpoint is public and needs no auth header. The token in the URL is the auth. Images, PDFs, and plain text (.txt, .log, .md) are served inline, with the type taken from the file extension. Everything else (JSON, HAR) downloads as an attachment. 404 means unknown, revoked, or expired; 503 with Retry-After means storage is briefly unavailable and the link is still valid. A successful download carries Cache-Control: no-store and X-Robots-Tag: noindex, nofollow.
Errors
Errors are JSON: {"error": "<message>", "code": "<code>"}. Branch on code.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | file_type_not_allowed |
The file type is not in the allowed list. |
| 400 | secret_detected |
The scan found secret-shaped content and on_secret is reject, so nothing was stored. |
| 400 | invalid_request |
A parameter is not valid, for example a ttl_days that is not a whole number. |
| 401 | unauthorized |
The API key is missing or not valid. When a team member's key is refused because the team is on Free, the sentence says so, and the key works again once the team pays. |
| 402 | storage_cap_reached |
The workspace has reached its plan's storage cap. Revoke files you no longer need, or upgrade. A member of a team reads that their administrator can choose a larger plan under Billing. |
| 403 | file_held |
This file is held, so it was not revoked. |
| 403 | team_on_free |
A key request answers with "Your team is on the Free plan, so no key was made. Ask your administrator to choose a paid plan under Billing." An upload answers with "Your team is on the Free plan, so nothing was stored. Ask your administrator to choose a paid plan under Billing." |
| 404 | not_found |
The id or token is unknown, or the file is revoked or expired. |
| 409 | not_enough_seats |
This team has more people than the plan has seats. Remove people first. (POST /api/v1/billing/checkout and POST /api/v1/billing/switch, with plan, people and seats.) |
| 413 | file_too_large |
The file is larger than 25 MiB. |
| 429 | monthly_cap_reached |
The workspace has reached its plan's monthly upload cap. Uploads work again next month, or you can upgrade. A member of a team reads that their administrator can choose a larger plan under Billing. |
| 429 | rate_limited |
There were too many requests. Wait the number of seconds in Retry-After, then try again. |
The rate limit is 100 uploads per hour for each API key or connected app, and REST and MCP uploads share it.
The full technical reference, including MCP and billing endpoints, is API.md.