Alertedly
REST API · v1.12.0

Weekly competitive intelligence, over HTTP.

Companies, signals, metrics, leaderboards, digests, reports and agent-ready markdown, for every company you or your firm track. The same research your weekly reports and your AI assistant read, as JSON.

Quick start
Auth
X-API-Key or Bearer token
Limits
60 / min per person, 600 / min per firm
GET /signalsExample
$ curl -H "X-API-Key: $ALERTEDLY_API_KEY" \
  "https://api.alertedly.com/api/v1/signals?severity=high"HTTP/2 200
x-api-version: 1.12.0
x-ratelimit-limit: 60{  "week": "2026-10-05",  "total": 14,  "counts": { "critical": 0, "high": 3, "medium": 6, "low": 5, "total": 14 },  "signals": [    {      "company_name": "Northwind",      "lens": "portfolio",      "channel": "website_screenshot",      "type": "pricing_change",      "severity": "high",      "title": "Enterprise tier added",      "source_urls": ["https://northwind.example/pricing"],      "created_at": "2026-10-06T..."    }  ],  "request_id": "uuid"}
DocsAPI reference
On this page

Overview

  • Data is researched once a week per company and served read-only. Reading never triggers new research.
  • Base URL: https://api.alertedly.com/api/v1.
  • Weeks are ISO weeks in UTC. A week parameter accepts any date and uses the first day of that ISO week.
  • API keys are available on the Pro plan and on VC plans. See Pricing.
  • OpenAPI 3 spec: /docs/openapi.yaml. Postman collection: /docs/alertedly-api.postman.json.
  • For AI assistants, the MCP server gives the same data with per-person sign-in.

Authentication

Every endpoint except /health needs an API key:

terminal
curl -H "X-API-Key: $ALERTEDLY_API_KEY" https://api.alertedly.com/api/v1/companies

Authorization: Bearer YOUR_KEY also works.

  • Key
    Personal key
    Created by
    You
    Where
    Dashboard → API key
    Sees
    Your tracked companies; your firm's if you belong to one
  • Key
    Organization key
    Created by
    A firm admin
    Where
    Team settings
    Sees
    The firm's portfolio and dealflow

Keys are stored as hashes and shown once at creation. Revoke a key at any time where you created it; it stops working immediately.

Scopes and expiry

  • Scope
    read
    Allows
    GET requests
  • Scope
    write
    Allows
    POST, PUT, PATCH and DELETE requests (adding, updating, converting and removing companies; VC workflow changes)

A request without the needed scope returns 403 with INSUFFICIENT_SCOPE. Keys can have an expiry date; expired keys return 401. Use read-only keys with an expiry for automations.

Firms and ?org=

A personal key of someone in one firm sees that firm. If you belong to several firms, add ?org= with the firm's name or slug to any request; without it, your earliest membership is used.

terminal
curl -H "X-API-Key: $ALERTEDLY_API_KEY" "https://api.alertedly.com/api/v1/signals?org=fund-ii"

Report endpoints return only your account's reports (personal scope) or reports belonging to your firm's members (firm scope). You never see another account's or another firm's data.

Rate limits

  • Limit
    Per person
    Applies to
    Each signed-in user, or each organization API key
    Value
    60 requests / minute
  • Limit
    Per firm
    Applies to
    All members and keys of one firm together
    Value
    600 requests / minute

Over the limit, the API returns 429 with a Retry-After header. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus X-Request-ID and X-API-Version.

Usage logging

Every request is logged with the key, the endpoint, the status and the time. Logging never blocks a response. See your usage with GET /usage; firm admins also see the firm's AI and API activity in Team settings.

Channels

Alertedly collects 16 channels. Careers, Meta ads, Google ads, LinkedIn ads, Reddit, reviews (G2 and Trustpilot) and trademarks are Pro and VC channels. The /channels endpoint uses the keys below; report returns the cross-channel weekly report.

  • Channel
    Press and news
    Weekly data key
    press
    /channels key
    news
  • Channel
    Website and blog
    Weekly data key
    website_blog
    /channels key
    website_blog (alias blog)
  • Channel
    Changelog
    Weekly data key
    changelog
    /channels key
    changelog
  • Channel
    Website changes
    Weekly data key
    website_screenshot
    /channels key
    website_changes (alias website)
  • Channel
    Careers
    Weekly data key
    careers
    /channels key
    careers
  • Channel
    LinkedIn
    Weekly data key
    linkedin
    /channels key
    linkedin
  • Channel
    X
    Weekly data key
    twitter
    /channels key
    twitter
  • Channel
    Instagram
    Weekly data key
    instagram
    /channels key
    instagram
  • Channel
    YouTube
    Weekly data key
    youtube
    /channels key
    youtube
  • Channel
    TikTok
    Weekly data key
    tiktok
    /channels key
    tiktok
  • Channel
    Meta ads
    Weekly data key
    meta_ads
    /channels key
    meta_ads (alias meta-ads)
  • Channel
    Google ads
    Weekly data key
    google_ads
    /channels key
    google_ads
  • Channel
    LinkedIn ads
    Weekly data key
    linkedin_ads
    /channels key
    linkedin_ads
  • Channel
    Reddit
    Weekly data key
    reddit
    /channels key
    reddit
  • Channel
    Reviews (G2 and Trustpilot)
    Weekly data key
    reviews
    /channels key
    reviews
  • Channel
    Trademarks (USPTO)
    Weekly data key
    trademarks
    /channels key
    use /signals and /metrics?channel=trademarks

Health

GET/healthscope read

No auth required. Returns API status and version.

200 OK
{
  "status": "healthy",
  "version": "1.12.0",
  "timestamp": "2026-10-08T09:28:58.712Z",
  "request_id": "uuid"
}

Companies

List companies

GET/companies?status=portfolio&limit=100&offset=0scope read
  • Param
    status
    Default
    all
    Description
    portfolio or dealflow (firm scope)
  • Param
    limit
    Default
    100
    Description
    Max 500
  • Param
    offset
    Default
    0
    Description
    Pagination offset
200 OK
{
  "companies": [
    {
      "id": "uuid",
      "name": "Northwind",
      "website": "northwind.example",
      "status": "portfolio",
      "added_at": "2026-01-15T...",
      "last_researched_at": "2026-10-05T...",
      "social_urls": { "linkedin": "https://linkedin.com/company/...", "twitter": "https://x.com/..." }
    }
  ],
  "pagination": { "total": 12, "limit": 100, "offset": 0, "has_more": false }
}

Get company

GET/companies/{id}scope read

Company details, discovered social URLs and per-channel data freshness.

Add company

POST/companiesscope write
request body
{ "name": "Acme Labs", "website": "acmelabs.example", "status": "dealflow" }
  • Field
    name
    Required
    yes
    Description
    Company name
  • Field
    website
    Required
    yes
    Description
    Company website
  • Field
    status
    Required
    no
    Description
    portfolio or dealflow (default dealflow). Portfolio needs a firm admin.

Returns 201 with { id, name, website, status, message }. Counts against your plan's or firm's company limit.

Update company

PUT/companies/{id}scope write
request body
{ "status": "portfolio" }

Moves a dealflow company to the portfolio when the firm invests (firm scope, admins). One way, as in the dashboard: a portfolio company never moves back to dealflow (409 ONE_WAY_MOVE; remove it and add it again if it went on the wrong list). Returns { id, previous_status, new_status, updated: true }.

Delete company

DELETE/companies/{id}scope write

Stops tracking the company. Returns { id, deleted: true }.

Convert status

POST/companies/{id}/convertscope write

Moves a dealflow company to the portfolio (firm scope, admins; personal scope returns 400 NOT_SUPPORTED). A portfolio company answers 409 ONE_WAY_MOVE. Returns { id, previous_status, new_status }.

Channel data

GET/channels/{channel}/{company_id}?days=30scope read
  • Param
    days
    Default
    30
    Description
    Look-back period

Structured intelligence for one channel. See Channels for keys.

200 OK
{
  "channel": "reddit",
  "company_id": "uuid",
  "time_range": { "days": 30, "from": "...", "to": "..." },
  "metrics": { "sentiment_score": 0, "thread_count": 5, "net_sentiment": "positive" },
  "analysis": "...",
  "last_updated": "2026-10-05T...",
  "data_points": 3,
  "raw_items": 12,
  "history": [ { "generated_at": "...", "content": { } } ]
}

Events

GET/companies/{id}/events?days=7&severity=mediumscope read

GET /events/{company_id} is an equivalent alias.

  • Param
    days
    Default
    7
    Description
    Look-back period
  • Param
    severity
    Default
    all
    Description
    low, medium, high or critical

Signal types written by the weekly pipeline:

  • Signal type
    raise_detected
    Meaning
    A funding round was announced or reported
  • Signal type
    product_launch
    Meaning
    A new product, feature or major release
  • Signal type
    pricing_change
    Meaning
    Pricing or plans changed
  • Signal type
    hiring_spree
    Meaning
    Open roles grew sharply
  • Signal type
    hiring_slowdown
    Meaning
    Open roles fell sharply
  • Signal type
    layoffs
    Meaning
    Layoffs reported
  • Signal type
    leadership_change
    Meaning
    Executive hires or departures
  • Signal type
    partnership
    Meaning
    A new partnership or integration
  • Signal type
    acquisition
    Meaning
    Acquired something, or was acquired
  • Signal type
    legal_regulatory
    Meaning
    Lawsuits, regulatory or compliance news
  • Signal type
    sentiment_shift
    Meaning
    Public sentiment moved noticeably
  • Signal type
    competitor_move
    Meaning
    A competitor did something relevant to this company

Older reports may contain other types (for example hiring_surge). Treat event_type as an open string.

Ads and reviews

Pro and VC firms. The same answers as the MCP tools get_ads and get_reviews. Ad copy and review text come from the web and are cleaned like every other third-party text.

GET/companies/{id}/ads?platforms=google,linkedin&since=2026-09-01&detail=briefscope read
  • Param
    platforms
    Default
    meta,google,linkedin
    Description
    Comma-separated ad libraries
  • Param
    since
    Default
    every ad of the latest weekly collection
    Description
    Only ads started on or after this date (and signals since it; default 30 days)
  • Param
    detail
    Default
    brief
    Description
    brief (25 creatives per platform) or full (100)

Both cover the latest weekly report window: exactly 7 days (the last completed ISO week, or for a first report the 7 days before it ran). Per platform: status (active, quiet = no ads in the window, not_tracked = never researched for this company, unavailable = no research newer than 8 days (see as_of), this week's run could not read it, or the Google advertiser could not be verified), counts by freshness (newly_launched = launch date inside the window, newly_observed = first seen this week with an unknown launch date, existing_unknown), coverage (how much of the library was read; sample when the read was capped), Google advertiser verification and third_party_ads (never counted), notes, the weekly summary and the creatives, newly launched first, each with its freshness and ad library link in url. A count that could not be determined is null, never 0.

200 OK
{
  "company_id": "uuid",
  "company": "Northwind",
  "since": "2026-09-08",
  "platforms": [
    {
      "platform": "google", "channel": "google_ads", "status": "active", "as_of": "2026-10-05", "week": "2026-10-05",
      "window": { "start": "2026-09-28T00:00:00.000Z", "end": "2026-10-05T00:00:00.000Z", "mode": "scheduled", "from": "2026-09-28", "to": "2026-10-04" },
      "counts": { "active_ads": 4, "newly_launched": null, "newly_observed": null, "existing_unknown": null, "new_ads": null },
      "coverage": { "retrieved": 40, "vendor_total": 300, "vendor_total_label": "Google's estimate, all-time", "cap": 2, "cap_unit": "pages", "capped": true, "complete": false, "sample": true },
      "advertiser": { "status": "verified", "verified": [{ "id": "AR13...", "name": "Northwind, Inc.", "count": 40 }], "unverified": [] },
      "third_party_ads": { "count": 0, "advertisers": [], "without_advertiser_id": null },
      "notes": ["Google: how many ads were newly launched could not be determined this week (a capped sample was read): unknown, not zero."],
      "metrics": { "active_ads": 4, "coverage_complete": 0, "ads_estimate": 300 },
      "summary": { "activity": "active", "summary": "...", "highlights": [], "signals": [], "generated": "2026-10-05" },
      "creatives": [
        { "platform": "google", "ad_id": "CR0922...", "url": "https://adstransparency.google.com/advertiser/.../creative/...",
          "format": "video", "body": "", "first_shown": "2026-06-16T...", "last_shown": "2026-10-05T...", "regions": ["US"],
          "impressions_min": null, "impressions_max": null, "freshness": "existing_unknown", "new_this_week": false }
      ],
      "creatives_total": 4
    }
  ],
  "totals": { "active_ads": 4, "newly_launched": null, "new_ads": null, "active_platforms": ["google"], "unknown": { "active_ads": [], "newly_launched": ["google"] } },
  "signals": [],
  "request_id": "uuid"
}
GET/companies/{id}/reviews?platform=trustpilot&max_rating=2&since=2026-09-01scope read
  • Param
    platform
    Default
    both
    Description
    g2 or trustpilot
  • Param
    min_rating / max_rating
    Default
    none
    Description
    Stars, 0-5 (max_rating=2 for complaints)
  • Param
    since
    Default
    every review of the latest weekly collection
    Description
    Only reviews published on or after this date (and signals since it; default 30 days)
  • Param
    detail
    Default
    brief
    Description
    brief (25 reviews) or full (100)
200 OK
{
  "company_id": "uuid",
  "company": "Northwind",
  "since": "2026-09-01",
  "review_status": "active",
  "as_of": "2026-10-05",
  "window": { "start": "2026-09-28T00:00:00.000Z", "end": "2026-10-05T00:00:00.000Z", "mode": "scheduled", "from": "2026-09-28", "to": "2026-10-04" },
  "metrics": { "g2_new_reviews": 6, "g2_avg_rating_week": 4.83, "trustpilot_new_reviews": 1, "trustpilot_avg_rating_week": 1, "low_ratings_week": 1, "replied_pct_week": 0, "platforms_read": 2 },
  "by_platform": [
    { "platform": "g2", "status": "ok", "new_reviews": 6, "avg_rating_week": 4.83, "coverage": { "retrieved": 6, "cap": 15, "capped": false, "complete": true, "sample": false } },
    { "platform": "trustpilot", "status": "ok", "new_reviews": 1, "avg_rating_week": 1, "trust_score": 2.2, "late_arrivals_added": 1 }
  ],
  "summary": { "activity": "active", "summary": "...", "highlights": ["..."], "signals": [], "generated": "2026-10-05" },
  "reviews": [
    { "platform": "trustpilot", "review_id": "...", "url": "https://www.trustpilot.com/reviews/...", "rating": 1, "title": "...",
      "body": "...", "published_at": "2026-10-01T10:27:18Z", "has_reply": false, "reply": null, "new_this_week": true }
  ],
  "reviews_total": 1,
  "signals": [ { "title": "...", "type": "sentiment_shift", "severity": "high", "channel": "reviews", "source_urls": ["https://..."] } ],
  "request_id": "uuid"
}

Portfolio (bulk)

Intelligence or events for every tracked company in one call.

GET/portfolio/intelligence?scope=all&channels=careers,changelog&since=2026-09-01&full=false&limit=50&offset=0scope read
  • Param
    scope
    Default
    all
    Description
    all, portfolio or dealflow
  • Param
    channels
    Default
    all channels
    Description
    Comma-separated channel keys
  • Param
    since
    Default
    7 days ago
    Description
    ISO date; only data generated since
  • Param
    full
    Default
    false
    Description
    true returns full content instead of a summary
  • Param
    limit
    Default
    50 (max 100); 25 when full=true
    Description
    Companies per page
  • Param
    offset
    Default
    0
    Description
    Pagination offset (by company)
GET/portfolio/events?scope=all&days=7&severity=high&limit=100&offset=0scope read
  • Param
    scope
    Default
    all
    Description
    all, portfolio or dealflow
  • Param
    days
    Default
    7
    Description
    Look-back period
  • Param
    severity
    Default
    all
    Description
    low, medium, high or critical
  • Param
    channels
    Default
    all
    Description
    Comma-separated channels, e.g. reviews, google_ads; ads = Meta, Google and LinkedIn ads
  • Param
    limit
    Default
    100 (max 200)
    Description
    Companies per page
  • Param
    offset
    Default
    0
    Description
    Pagination offset

VC: signals, metrics, leaderboard, digest

Weekly views across everything you track. All four take week (any date, normalized to the start of its ISO week; default: the current week). Invalid parameters return 400 with INVALID_WEEK or INVALID_PARAMETER.

Signals

GET/signals?week=2026-10-05&company_id=uuid&severity=high&limit=200scope read
  • Param
    week
    Default
    current week
    Description
    Any date in the week
  • Param
    company_id
    Default
    all companies
    Description
    Limit to one tracked company (404 if not in your tracking)
  • Param
    severity
    Default
    all
    Description
    Exactly this severity: critical, high, medium or low
  • Param
    channels
    Default
    all
    Description
    Comma-separated channels; ads = Meta, Google and LinkedIn ads
  • Param
    limit
    Default
    200
    Description
    1-500

Sorted by severity, then newest first. counts covers all signals of the week, before limit.

200 OK
{
  "week": "2026-10-05",
  "total": 14,
  "counts": { "critical": 0, "high": 3, "medium": 6, "low": 5, "total": 14 },
  "signals": [
    {
      "id": "uuid",
      "company_id": "uuid",
      "company_name": "Northwind",
      "lens": "portfolio",
      "channel": "website_screenshot",
      "type": "pricing_change",
      "severity": "high",
      "title": "Enterprise tier added",
      "summary": "...",
      "source_urls": ["https://..."],
      "created_at": "2026-10-06T...",
      "is_actionable": true
    }
  ],
  "request_id": "uuid"
}

lens is portfolio or dealflow for firm scope, and null for personal scope.

Metrics

GET/metrics?week=2026-10-05&channel=careers&company_id=uuidscope read
  • Param
    week
    Default
    current week
    Description
    Any date in the week
  • Param
    channel
    Default
    all channels
    Description
    Channel key, e.g. careers, meta_ads, trademarks, linkedin; ads = the three ad libraries; social = the company's own LinkedIn, X, Instagram, YouTube and TikTok, with posts summed per company (social.posts, per channel, unknown channels listed, never 0) and most posts first
  • Param
    company_id
    Default
    all companies
    Description
    Limit to one tracked company
200 OK
{
  "week": "2026-10-05",
  "channel": "careers",
  "companies": [
    {
      "company_id": "uuid",
      "name": "Northwind",
      "lens": "portfolio",
      "channels": {
        "careers": { "open_roles": 41, "new_roles": 9, "removed_roles": 2, "leadership_roles": 2 }
      }
    }
  ],
  "request_id": "uuid"
}

Leaderboard

GET/leaderboard?week=2026-10-05&limit=5scope read
  • Param
    week
    Default
    current week
    Description
    Any date in the week; compared with the week before
  • Param
    limit
    Default
    5
    Description
    Entries per ranking, 1-50 (ties at the cut-off are kept)
  • Ranking
    hiring_growth
    Meaning
    Largest increase in open roles versus last week
  • Ranking
    hiring_slowdown
    Meaning
    Largest decrease in open roles (value is negative)
  • Ranking
    social_activity
    Meaning
    Posts across LinkedIn, X, Instagram, TikTok and YouTube
  • Ranking
    ads
    Meaning
    Active ads on Meta, Google and LinkedIn together
  • Ranking
    new_trademarks
    Meaning
    New USPTO trademark applications
200 OK
{
  "week": "2026-10-05",
  "prev_week": "2026-09-28",
  "companies": [
    {
      "company_id": "uuid",
      "name": "Northwind",
      "hiring": { "source": "board", "open_roles": 41, "prev_open_roles": 32, "delta": 9, "new_roles": 9, ... },
      "social": { "posts": 14, "engagement": 820, "by_channel": { "linkedin": { "posts": 6, "engagement": 540 } } },
      "ads": { "active_ads": 12, "new_ads": 3 },
      "trademarks": { "filings": 4, "new_applications": 1 },
      "signals": { "critical": 0, "high": 1, "medium": 2, "low": 0, "total": 3 }
    }
  ],
  "rankings": {
    "hiring_growth": [ { "company_id": "uuid", "name": "Northwind", "value": 9, "rank": 1 } ],
    "hiring_slowdown": [],
    "social_activity": [],
    "ads": [],
    "new_trademarks": []
  },
  "request_id": "uuid"
}

Hiring delta is only computed when last week used the same source and this week isn't zero; otherwise it is null.

Digest (the week's signals)

GET/digest?week=2026-10-05&limit=5scope read

The week's raw material for the firm: each company's report status and signals, by portfolio and dealflow, and the hiring and activity rankings. For the written Portfolio and Dealflow round-ups and the combined firm report, use GET /weekly-reports. Firm scope only; personal scope returns 403 FORBIDDEN.

  • Param
    week
    Default
    current week
    Description
    Any date in the week
  • Param
    limit
    Default
    5
    Description
    Entries per leaderboard ranking, 1-50
200 OK
{
  "org": { "id": "uuid", "name": "Example Ventures" },
  "week": "2026-10-05",
  "groups": {
    "portfolio": {
      "companies": [
        {
          "company_id": "uuid",
          "name": "Northwind",
          "lens": "portfolio",
          "status": "ready",
          "headline": "...",
          "report_url": "https://alertedly.com/...",
          "signals": { "critical": 0, "high": 1, "medium": 2, "low": 0, "total": 3 }
        }
      ],
      "signals": [ { "company_name": "Northwind", "type": "pricing_change", "severity": "high", "source_urls": ["https://..."], ... } ]
    },
    "dealflow": { "companies": [], "signals": [] }
  },
  "pending": [ { "name": "Acme Labs", "status": "pending", ... } ],
  "leaderboard": { "week": "2026-10-05", "prev_week": "2026-09-28", "companies": [], "rankings": { } },
  "totals": { "companies": 24, "ready": 22, "signals": { "critical": 0, "high": 3, "medium": 6, "low": 5, "total": 14 } },
  "request_id": "uuid"
}

Company status is ready, pending (this week's run hasn't finished) or failed.

VC workflow (v1.7.0)

The same features as the VC dashboard and the MCP server, built on the same database functions, so the numbers and the role rules match everywhere. Full request and response shapes are in the OpenAPI file (tag VC workflow).

  • Firms only. Use a firm key, or a personal key of a firm member (?org= picks the firm). Personal accounts get 403 ORG_ONLY.
  • Writes need a person. Changes need a personal key of a member with write scope, so every change is recorded under that person and checked against their role. Firm-wide keys can read; their writes get 403 USER_KEY_REQUIRED.
  • Roles. Any member may triage, add notes, edit dealflow companies, create personal alert rules and share links (unless the firm limits sharing to admins). Portfolio company details, firm-wide alert rules, firm settings and the jobs board need an admin (403 ADMIN_REQUIRED).
  • Confirm. Changes to portfolio companies, alert rules, revoking links, import commits, CRM pushes and firm settings need "confirm": true in the body (?confirm=true on DELETE). Without it you get 428 CONFIRM_REQUIRED and a preview of what would change.
  • Agents draft, humans send. Only POST /lp-highlights/generate may write prose (once per firm and period, within a monthly allowance). /board-pack and /founder-draft return the saved text or a template and never generate.
  • Rate limits. Each key has its own per-minute limit, and the whole firm shares 600 requests a minute across every member and key, the REST API and MCP together. Over a limit the answer is 429 RATE_LIMITED with Retry-After (seconds) and a message saying when to retry.
  • Private. Notes and reviews (triage) stay in the firm: notes only come back from /companies/{id}/notes. Secrets (Slack URLs, CRM keys) go in on the site or with POST /integrations and are never sent back. API keys are created on the site only.
  • Not installed yet. If a feature has not reached your firm yet the answer is 501 FEATURE_NOT_AVAILABLE.
  • Endpoint
    GET /momentum?status=&sort=&flags=
    Scope
    read
    What it does
    Momentum 0-100, change vs 4 weeks ago, flags, drivers, why it needs attention; companies building a baseline listed separately
  • Endpoint
    GET /movers?week=&lens=
    Scope
    read
    What it does
    This week's top movers (signal points plus hiring change, with the reason and source) and the companies that went quiet, as Home shows them
  • Endpoint
    GET /ai-usage?days=&limit=
    Scope
    read
    What it does
    MCP and API calls by the firm (admins: everyone plus a per-member summary; members: their own)
  • Endpoint
    GET /board-pack?company=&from=&to=
    Scope
    read
    What it does
    Since the last board meeting (or a range): changes, competitor moves, activity, silence, founder questions, saved summary if any
  • Endpoint
    GET /period-summary?type=&period=&lens=&tags=
    Scope
    read
    What it does
    Month, quarter or year numbers and highlights
  • Endpoint
    GET /review?type=&period=&lens=
    Scope
    read
    What it does
    Month, Quarter or Year in Review cards
  • Endpoint
    GET /weekly-reports?kind=&week=
    Scope
    read
    What it does
    The weekly round-up: portfolio, dealflow or the combined firm report (default), newest week by default
  • Endpoint
    GET /weekly-reports/weeks
    Scope
    read
    What it does
    The weeks with a round-up, newest first, with their kinds
  • Endpoint
    GET /value-report?type=&period=
    Scope
    read
    What it does
    Research checks covered, signals caught early, firm activity
  • Endpoint
    GET /jobs?function=&location=&company=&new_since=
    Scope
    read
    What it does
    Open roles across portfolio companies
  • Endpoint
    GET /lp-highlights?type=&period=
    Scope
    read
    What it does
    The firm's saved LP highlights draft (never generates)
  • Endpoint
    POST /lp-highlights/generate
    Scope
    write
    What it does
    Writes the LP draft once per firm and period, or returns the saved one
  • Endpoint
    GET /founder-draft?signal=&intent=
    Scope
    read
    What it does
    Saved or template founder message, with placeholders
  • Endpoint
    GET, POST /share-links · DELETE /share-links/{id}
    Scope
    read / write
    What it does
    List, create (one click, reused) and revoke (confirm) read-only links
  • Endpoint
    POST /signals/{id}/triage
    Scope
    write
    What it does
    Review a signal (the dashboard's Review): acted_on, check_in, watching, ignore or clear; assignee and note
  • Endpoint
    GET, POST /companies/{id}/notes
    Scope
    read / write
    What it does
    Firm-private notes
  • Endpoint
    PATCH /companies/{id}
    Scope
    write
    What it does
    Owner, stage, board dates, tags, fund (portfolio: admin + confirm)
  • Endpoint
    POST /companies/import
    Scope
    write
    What it does
    Up to 200 companies; dry run by default, commit with confirm
  • Endpoint
    POST /portfolio/from-site
    Scope
    write
    What it does
    Find the companies on the firm's website portfolio page (admins; 10 an hour per firm; waits up to 40 s, else 202 with scan_id; nothing added: import the confirmed ones with POST /companies/import)
  • Endpoint
    GET /portfolio/from-site/{scan_id}
    Scope
    read
    What it does
    A website scan's result: the companies found (200), or still reading (202)
  • Endpoint
    POST /companies/{id}/crm-sync
    Scope
    write
    What it does
    Note with public signals to Attio, HubSpot or Notion (confirm)
  • Endpoint
    POST /companies/{id}/crm-match
    Scope
    write
    What it does
    Candidate CRM records for a company; save or remove a match, or add it to the CRM as a new record (admin + confirm)
  • Endpoint
    GET /crm/sync-log?company=&crm=&status=&limit=
    Scope
    read
    What it does
    What was sent to the CRM: notes added, skipped and failed, each with its fix
  • Endpoint
    GET /crm/matches?crm=
    Scope
    read
    What it does
    Which companies the CRM matches and which need matching (up to 50, portfolio first; admin)
  • Endpoint
    GET, POST /alert-rules · PATCH, DELETE /alert-rules/{id}
    Scope
    read / write
    What it does
    Alert rules (changes need confirm)
  • Endpoint
    GET /alert-deliveries
    Scope
    read
    What it does
    Alert delivery log
  • Endpoint
    GET /integrations
    Scope
    read
    What it does
    Connection status and delivery heartbeats, no secrets
  • Endpoint
    GET, PATCH /settings
    Scope
    read / write
    What it does
    Firm settings: time zone, alert quiet hours, admin-only share links, jobs board (changes: admin + confirm)
  • Endpoint
    GET, PATCH /preferences
    Scope
    read / write
    What it does
    Your email preferences (including the Portfolio and Dealflow round-ups)
  • Endpoint
    GET /team
    Scope
    read
    What it does
    Members, your role, seats; for admins the pending invites
  • Endpoint
    POST /team/invites
    Scope
    write
    What it does
    Invite up to 500 people and email each an invite (admin + confirm)
  • Endpoint
    DELETE /team/invites/{id} · POST /team/invites/{id}/resend
    Scope
    write
    What it does
    Withdraw or resend an invite (admin + confirm)
  • Endpoint
    PATCH, DELETE /team/members/{id} · POST /team/leave
    Scope
    write
    What it does
    Change a role, remove a member, leave the firm (confirm)
  • Endpoint
    GET /team/members/{id}/offboarding
    Scope
    read
    What it does
    What removing a member would revoke
  • Endpoint
    DELETE /notes/{id}
    Scope
    write
    What it does
    Delete a note (author or admin + confirm)
  • Endpoint
    PUT /lp-highlights · POST /lp-highlights/pending
    Scope
    write
    What it does
    Edit the LP highlights draft, or take or dismiss a newer one
  • Endpoint
    GET /triage-counts · GET /companies/{id}/triage-log
    Scope
    read
    What it does
    What is left to review (To review); a company's review history (Decisions)
  • Endpoint
    GET /companies/{id}/momentum-history · GET /periods · GET /attention
    Scope
    read
    What it does
    Momentum week by week, report periods, what needs attention this week
  • Endpoint
    PATCH /firm
    Scope
    write
    What it does
    Rename the firm (admin + confirm)
  • Endpoint
    POST /integrations · PATCH, DELETE /integrations/{id}
    Scope
    write
    What it does
    Connect, change or remove Slack, webhooks and CRMs (admin + confirm); secrets are never sent back
  • Endpoint
    GET /api-keys · DELETE /api-keys/{id}
    Scope
    read / write
    What it does
    The firm's API keys, and revoking one (admin); keys are created on the site

Example: board prep and a confirmed change

terminal
# Board pack since the last board meeting
curl -H "X-API-Key: $ALERTEDLY_API_KEY" "https://api.alertedly.com/api/v1/board-pack?company=COMPANY_ID"

# Set the next board meeting on a portfolio company: preview first (428 CONFIRM_REQUIRED with a preview)
curl -X PATCH -H "X-API-Key: $ALERTEDLY_API_KEY" -H "Content-Type: application/json" -d '{"next_board_meeting":"2026-11-12"}' "https://api.alertedly.com/api/v1/companies/COMPANY_ID"

# ...then confirm
curl -X PATCH -H "X-API-Key: $ALERTEDLY_API_KEY" -H "Content-Type: application/json" -d '{"next_board_meeting":"2026-11-12","confirm":true}' "https://api.alertedly.com/api/v1/companies/COMPANY_ID"

Competitors

GET/companies/{id}/competitorsscope read

Discovered competitors, sorted by confidence score.

200 OK
{
  "company_id": "uuid",
  "competitors": [
    {
      "id": "uuid",
      "name": "Copperleaf",
      "domain": "copperleaf.example",
      "reason": "Same buyer, overlapping features",
      "confidence_score": 92,
      "first_discovered": "2026-01-15T...",
      "last_updated": "2026-09-20T...",
      "tracked_company_id": "uuid or null"
    }
  ],
  "total": 10
}

Markdown (agent-ready)

GET/companies/{id}/markdown?channel=redditscope read
  • Param
    channel
    Default
    none
    Description
    Optional channel key. Omit for the full weekly report.

Returns { company_id, channel, source, generated_at, markdown, format: "text/markdown" }.

Reports

Report endpoints return only your account's reports, or your firm members' reports for firm scope.

List reports

GET/reports?company_id=uuid&limit=50&offset=0scope read

limit max 200 (default 50); company_id optional. Returns { reports: [{ id, company_id, company_name, report_date, file_type, created_at }], pagination }.

Latest reports

GET/reports/latest?scope=portfolio&since=2026-09-01&limit=50&offset=0scope read
  • Param
    scope
    Default
    portfolio
    Description
    portfolio, dealflow or all
  • Param
    since
    Default
    7 days ago
    Description
    ISO date
  • Param
    limit
    Default
    50
    Description
    Max 100
  • Param
    offset
    Default
    0
    Description
    Pagination offset

Get report

GET/reports/{id}scope read

Report metadata plus all channel data for that report's period. An investor report (portfolio or dealflow) opens with What changed: since last week and since your firm added the company, every number computed from stored weekly data (channel metrics with their trend, new and continuing developments, signals by severity; the first week tracked says so). Then Alertedly's take, our labeled interpretation with what would confirm it, kept apart from the facts. It ends with a coverage line: when it was researched, how many channels had data and which did not, and how many items were read. MCP get_company_brief returns the same as changes, alertedly_take and coverage.

Latest report for a company

GET/companies/{id}/latest-reportscope read

Returns { id, company_id, report_date, file_url, file_type, created_at }.

Voice summary

GET/voice-summary/{report_id}scope read

The audio briefing for one of your reports: { report_id, report_date, voice_generated, audio_url, script, format }.

Usage

GET/usage?days=30&all=truescope read
  • Param
    days
    Default
    30
    Description
    Historical window
  • Param
    all
    Default
    false
    Description
    true for firm-wide stats (organization keys)
200 OK
{
  "summary": { "total_requests": 1248, "period_requests": 312, "avg_latency": 142, "rate_limit": 60, "last_used_at": "..." },
  "recent_usage": [ { "endpoint": "/companies", "method": "GET", "status_code": 200, "created_at": "...", "response_time_ms": 120 } ],
  "request_id": "uuid"
}

Errors

error body
{
  "error": { "message": "...", "error_code": "INSUFFICIENT_SCOPE" },
  "request_id": "uuid"
}
  • Code
    UNAUTHORIZED
    Status
    401
    Meaning
    Missing, invalid, revoked or expired API key
  • Code
    INSUFFICIENT_SCOPE
    Status
    403
    Meaning
    The key lacks the scope this method needs (read for GET, write otherwise)
  • Code
    FORBIDDEN
    Status
    403
    Meaning
    Not allowed for this key or person (e.g. /digest without firm scope, portfolio without admin, org you are not in)
  • Code
    NOT_FOUND
    Status
    404
    Meaning
    Resource not found, or not in your tracking
  • Code
    VALIDATION_ERROR
    Status
    400
    Meaning
    Missing or invalid parameters
  • Code
    INVALID_PARAMETER / INVALID_WEEK
    Status
    400
    Meaning
    A VC endpoint parameter is out of range or malformed
  • Code
    INVALID_CHANNEL
    Status
    400
    Meaning
    Unknown channel key
  • Code
    NOT_SUPPORTED
    Status
    400
    Meaning
    Operation not supported for this key type
  • Code
    ORG_ONLY
    Status
    403
    Meaning
    VC workflow endpoint called with a personal (non-firm) account
  • Code
    USER_KEY_REQUIRED
    Status
    403
    Meaning
    VC workflow change with a firm-wide key: use a member's personal key
  • Code
    ADMIN_REQUIRED
    Status
    403
    Meaning
    The change needs a firm admin
  • Code
    CONFIRM_REQUIRED
    Status
    428
    Meaning
    Send "confirm": true to apply; the body carries a preview
  • Code
    FEATURE_NOT_AVAILABLE
    Status
    501
    Meaning
    The feature has not reached your firm yet
  • Code
    RATE_LIMITED
    Status
    429
    Meaning
    Too many requests; wait for Retry-After
  • Code
    DATABASE_ERROR / INTERNAL_ERROR
    Status
    500
    Meaning
    Server error; retry, and contact support with the request_id if it persists

Quick start

terminal
export ALERTEDLY_API_KEY="your_key"

# Your companies
curl -H "X-API-Key: $ALERTEDLY_API_KEY" https://api.alertedly.com/api/v1/companies

# This week's signals, highest severity first
curl -H "X-API-Key: $ALERTEDLY_API_KEY" "https://api.alertedly.com/api/v1/signals"

# Who is hiring fastest this week
curl -H "X-API-Key: $ALERTEDLY_API_KEY" "https://api.alertedly.com/api/v1/leaderboard?limit=10"

# The firm's weekly digest (organization scope)
curl -H "X-API-Key: $ALERTEDLY_API_KEY" "https://api.alertedly.com/api/v1/digest"

# Agent-ready markdown for a company's latest report
curl -H "X-API-Key: $ALERTEDLY_API_KEY" https://api.alertedly.com/api/v1/companies/{company_id}/markdown