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: pip install veilfile, then veilfile login (browser approval flow), veilfile logout, and veilfile status. The full reference is in the API docs source.

Upload

POST /api/v1/artifacts

Multipart form:

Allowed types: png, jpg, jpeg, webp, gif, txt, md, log, json, har, 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: ask the user whether to keep or revoke the upload before sharing the link.

List

GET /api/v1/artifacts

Returns your workspace's artifacts, newest first.

Revoke

DELETE /api/v1/artifacts/<id>

Deletes the artifact at once. Its URL returns 404 immediately. Success is a 204 with an empty body. Unknown ids return 404.

Download

GET /a/<token>

Public. No auth. The token in the URL is the auth. Images, PDFs, and text are served inline. Everything else downloads as an attachment. Served with Cache-Control: no-store and X-Robots-Tag: noindex, nofollow.

Errors

Errors are JSON: {"error": "<code>", "message": "<detail>"}.

Rate limit: 100 uploads per hour per API key.

The full technical reference, including MCP and billing endpoints, is API.md.