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

http://35.239.106.129

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 http://35.239.106.129/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 http://35.239.106.129/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 http://35.239.106.129/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 http://35.239.106.129/api/reports/REPORT_ID/visibility \
  -H "Authorization: Bearer brk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

Prospecting — admin keys only

Search recent LinkedIn posts by phrase and have the model score each author as a prospect against an ICP. Runs in the background like a brief. These endpoints require an API key owned by an admin account (a key inherits its owner's permissions); a non-admin key gets 403.

POST/api/prospecting/searches

Start a prospecting search. Returns immediately with a search id and status: "queued".

curl -X POST http://35.239.106.129/api/prospecting/searches \
  -H "Authorization: Bearer brk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "raising our seed round",
    "days": "week",
    "max_posts": 40,
    "sort": "relevance",
    "icp": "Early-stage VCs who write first checks into AI startups"
  }'

query (required, 2–300 chars), days (24h | week | month, default week), max_posts (5–300, default 40), sort (relevance | date), icp (optional — who to score for; defaults to venture investors who research founders).

GET/api/prospecting/searches/{id}

Poll the search. status moves through queued → running → complete (or failed). When complete, results is an array of scored prospects, sorted by fit (highest first).

curl http://35.239.106.129/api/prospecting/searches/SEARCH_ID \
  -H "Authorization: Bearer brk_your_key_here"

# → {"id": "...", "status": "complete", "posts_count": 40,
#    "results": [
#      {
#        "name": "Jane Doe",
#        "headline": "Partner @ Acme Ventures",
#        "profile_url": "https://www.linkedin.com/in/janedoe",
#        "url": "https://www.linkedin.com/posts/janedoe_...",
#        "date": "2026-06-15T14:24:18.666Z",
#        "likes": 42, "comments": 7,
#        "fit_score": 9,
#        "fit_tag": "early-stage VC",
#        "reason": "Partner actively writing first checks into AI startups."
#      }
#    ]}

GET/api/prospecting/searches

List past searches (newest first). Query params: q, status, limit (≤100), offset. Returns { items, total } with each search's results omitted — fetch a single search by id for the full prospect list.

Lead Enricher — admin keys only

Take a list of leads (e.g. the prospecting CSV) and enrich the ones you choose: for each lead it scrapes the LinkedIn profile, summarizes recent activity, crawls and AI-summarizes the company, and resolves a work email. Appended columns: email, email_source, title, seniority, location, current_company, company_website, company_size, company_industry, company_summary, recent_activity. Runs async on the worker like a search.

POST/api/enrich/upload

Upload a CSV (multipart file) and get back its parsed rows + headers for preview/selection. The CSV must have a column whose header contains linkedin. No job is created yet.

POST/api/enrich/jobs

Start enrichment for the selected leads. Body: { leads: [ {…row}, … ], source_filename? } — each lead is a row dict; the enricher reads its LinkedIn / name / company columns. Returns a job id and status: "queued".

curl -X POST http://35.239.106.129/api/enrich/jobs \
  -H "Authorization: Bearer brk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"leads": [
        {"name": "Jane Doe", "company": "Acme",
         "linkedin_url": "https://www.linkedin.com/in/janedoe"}
      ]}'

GET/api/enrich/jobs/{id}

Poll a job. status moves queued → running → complete (or failed); pct is 0–100. When complete, results is each original row merged with the enrichment columns.

GET/api/enrich/jobs/{id}/csv

Download the enriched rows as a CSV (original columns + enrichment columns).

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.

Prospecting follows the same shape (admin keys only): POST /api/prospecting/searches to start, poll GET /api/prospecting/searches/{id} every ~3–5s until status === "complete" (these finish in seconds, not minutes), then read the results array — each item has name, profile_url, fit_score (1–10), fit_tag, reason, and the source post. Filter to fit_score >= 7 for the strongest leads. A 403 means the key isn't on an admin account.

Sutando Power Station

Briefroom is available as a cloud tool in the Sutando agent-universe power station. Install it once and your AI agent can generate briefs directly — no Briefroom account or API key needed. Billing runs through your Sutando credit wallet (2000 credits per brief).

How it works

The Sutando gateway calls Briefroom's MCP endpoint on your behalf. On your first brief, a Briefroom account is created silently and linked to your Sutando identity — all your briefs are tracked there and accessible at briefroom.ag2.ai.

Install Brief Room from the Sutando power station
Ask your agent: "Research [founder name] at [company]"
Agent calls GET /mcp/find (free) — finds the founder's LinkedIn URL and asks "Is this the right person?" before spending any credits
You confirm → agent calls briefroom__start_brief (2000 credits), tells you it started and will notify you when ready
Agent polls poll_url in the background every 60s — free, no credits, non-blocking
When complete (~5–12 min), agent notifies you with pdf_url to download

Credit model: only start_brief costs credits (2000 per brief). Find, poll, and list are always free — they call Railway directly, bypassing the gateway.

Gateway tool 2000 credits

Called via MCP at POST http://35.239.106.129/mcp — proxied by agent-universe, credits debited before reaching Railway.

briefroom__start_brief

Enqueue a founder brief. Required: name (comma-separated for co-founders). Optional: company, linkedin_url. Returns { job_id, poll_url, briefs_url, sutando_user_id }. Agent always calls /mcp/find first to confirm the founder before spending credits.

Free direct endpoints 0 credits

Called directly by the agent to Railway — bypass the gateway entirely, never billed.

GEThttp://35.239.106.129/mcp/find?name=&company=

Find a founder's LinkedIn URL before spending credits. No auth. Returns { linkedin_url, title, message } — agent shows this to the user and asks for confirmation before calling start_brief. Returns a clear error if name or company is missing.

GEThttp://35.239.106.129/mcp/poll/{job_id}

Poll a brief by job_id. No auth — UUID is unguessable. Returns status, pct, stage, and pdf_url / html_url once complete. Agent polls every 60s in a background cron — non-blocking.

GEThttp://35.239.106.129/mcp/briefs

List all briefs for this Sutando user. Pass X-Sutando-User-Id header (from start_brief response). Returns newest-first with status + artifact URLs. Optional: ?limit=20&offset=0.

More skills — the GTM - Prospecting room

Two more cloud tools run on this same API, forming a find → enrich flow:

Intent Leads 200 cr / run — intent-leads at http://35.239.106.129/mcp/prospecting. Searches recent LinkedIn posts for buying intent and ranks each author against your ICP. Returns a ranked CSV.

Lead Enricher 1000 cr / run (≤25 leads) — lead-enricher at http://35.239.106.129/mcp/enrich. Takes an Intent Leads run (or your own list) and, per lead, scrapes the profile, keeps recent posts verbatim, summarizes the company, and resolves a verified work email + phone. Returns one CSV (original columns + Enriched: columns) with the raw posts + intent signal for outreach. Up to 25 leads/run — for more, run again. Each tool's poll/csv endpoints are free, like Brief Room's.

Need a key? Head to your API keys page.