Docs

briefcast is tiny private hosting for files your AI agent generates — markdown or HTML. Upload a file, get a stable URL, share it. This page covers what's installed after npx briefcast init, how to call the API directly, and what the platform's defaults and limits are.

Install

In any git repo:

That writes .claude/skills/briefcast/SKILL.md so Claude Code in this repo gains a /briefcast skill. It then asks once whether you want to set a shared upload password for the team. If you say yes, it writes .briefcast to the repo root with default_password=<your-password>. Commit .briefcast so coworkers share the same default.

To install globally (skip the per-repo password prompt):

To accept all defaults non-interactively:

The /briefcast skill

After init, in any Claude Code session in this repo:

/briefcast README.md
/briefcast docs/architecture.md --ttl=7
/briefcast plan.html --no-password

The skill returns the URL and (unless you used --no-password) the password. Share both with the recipient.

Password resolution order, highest priority first:

1. --password="..." flag on the invocation
2. --no-password (skip the password gate entirely; private-by-obscurity only)
3. default_password=... in <repo-root>/.briefcast
4. A randomly chosen fun phrase (e.g. "blue elephant lawyer") as a one-off fallback

--ttl=<days> overrides the 30-day default. Range: 1–365.

API reference

The upload, delete, and health endpoints are open — no API key. Security comes from the password gate and the non-guessable 10-character slug.

POST /api/upload

Body fields:

• content (string, required) — file body, HTML or markdown source
• contentType ("html" | "markdown", required)
• password (string, optional) — PBKDF2-SHA256 hashed at rest
• ttlDays (number, optional, 1–365) — default 30

Response:

{
  "url": "https://briefcast-seven.vercel.app/b/abc123xyz",
  "slug": "abc123xyz",
  "deleteToken": "<32-char alphanumeric>",
  "expiresAt": 1750000000000,
  "ttlDays": 30
}

Limit: 8 MB per file.

POST /api/delete

The delete token (returned at upload time) IS the auth — no bearer needed. Save it if you ever want to delete or replace the brief.

GET /api/health

Liveness probe. Returns 200.

Defaults & limits

• TTL: 30 days unless overridden. Briefs are deleted automatically by a daily cron at 03:00 UTC.
• Slug: 10 characters from a 33-character alphabet (digits + lowercase, with 0, 1, and l removed for legibility).
• Password storage: PBKDF2-SHA256, 100,000 iterations, 16-byte salt. Raw passwords are never persisted.
• Delete token storage: SHA-256 hash. The raw token is returned exactly once at upload.
• File limit: 8 MB per upload.
• Rendering: HTML files load into a sandboxed <iframe sandbox="allow-scripts">. Markdown files are rendered to HTML server-side via marked (GFM, no breaks) then iframed the same way.
• Auth on upload: none. The /api/upload endpoint is open. To gate it, build your own.

Troubleshooting

HTTP 413 on upload. Your file is over 8 MB. Split it or compress it.

HTTP 400 with invalid_content_type. Only html or markdown are accepted. Other types are rejected.

HTTP 400 with missing_content. The body is empty or missing.

Password mismatch on view. The password gate is set per-brief at upload time. If you forgot the password, you can't recover it — re-upload with a new one (or share via --no-password).

Lost the delete token. There's no recovery. The brief will be deleted automatically at TTL expiry.

TTL expired. The brief is gone. Re-upload from the source file. The slug will be different (replace flow is on the roadmap as #6).