API documentation

Briefroom's REST API lets you generate and fetch deal briefs from code or an AI agent. Authenticate with an API key created in your dashboard. Calls act as your account and count against your plan quota.

Authentication

Pass your key as a bearer token on every request. Keys look likebrk_…and are shown only once at creation.

Authorization: Bearer brk_your_key_here

Base URL

https://api-production-da64d.up.railway.app

Endpoints

POST/api/reports

Create a brief. Returns immediately with a brief id andstatus: "queued"; generation runs in the background (~5 minutes).

curl -X POST https://api-production-da64d.up.railway.app/api/reports \
  -H "Authorization: Bearer brk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "founders": ["Jane Doe"],
    "company": "Acme Inc",
    "linkedin_urls": ["https://linkedin.com/in/janedoe"]
  }'

founders (1–4 names, required), company (optional), linkedin_urls (optional, aligned with founders).

GET/api/reports/{id}

Poll a brief's status. status moves through queued → running → complete (or failed); pct is 0–100. When complete, artifacts holds the HTML/PDF URLs.

curl https://api-production-da64d.up.railway.app/api/reports/REPORT_ID \
  -H "Authorization: Bearer brk_your_key_here"

# → {"id": "...", "status": "complete", "pct": 100,
#    "artifacts": {"html": "/api/reports/.../html", "pdf": "/api/reports/.../pdf"}}

GET/api/reports/{id}/html

Fetch the finished brief as a standalone HTML document.

GET/api/reports/{id}/pdf

Fetch the brief as a PDF.

curl https://api-production-da64d.up.railway.app/api/reports/REPORT_ID/pdf \
  -H "Authorization: Bearer brk_your_key_here" -o brief.pdf

POST/api/reports/{id}/visibility

Share a brief publicly (or make it private again). When public, anyone can open /reports/{id} on the Briefroom site without logging in.

curl -X POST https://api-production-da64d.up.railway.app/api/reports/REPORT_ID/visibility \
  -H "Authorization: Bearer brk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

For AI agents

This API is designed to be driven by autonomous agents (e.g. a Sutando skill). The full loop: POST /api/reports to start, then poll GET /api/reports/{id} every ~15s until status === "complete", then fetch /api/reports/{id}/html or /pdf. A 402 means the plan quota is exhausted; a 401 means the key is missing or revoked.

Need a key? Head to your API keys page.