1.6.0
Routes for combing through a workspace, finding what stands out, and exporting it next to your own data. See Exploring and exporting.
POST /posts/match. Resolve up to 100 post links from a campaign tracker, creator list, or post-performance report to posts on your team. Each link comes back in order asmatched,processing,failed,not_in_workspace,invalid_url, orunsupported_platform, andmeta.matchedPostIdsdrops straight intoselection.postIds. Nothing is added or charged.POST /posts/scan. One row per post across a selection, against the selection’s comment-weighted baseline, with flags for negative sentiment, posts well below or above the baseline, commenters arguing with each other, off-topic threads, content-vs-topic gaps, and highly engaged negative posts. Sort, filter by flag, page, or take every row as CSV.POST /breakdowns. Roll a selection up by account, platform, content tag, content type, collection, week, or month — the same math as the dashboard’s combined-by-account rows — with each group’s share of the selection and its difference from it.- Comparisons.
POST /analysestakescompare— 2 to 4 labeled selections — instead ofselection. Each side gets its own scope, content, and comment analysis;comparison.deltasgives each side against side 1.GET /analyses/{id}/comments?side=Nsamples one side. - Cited answers.
answer: { question }(oranswer: truefor an overview) writes the finding in words, with every claim citing real comments that resolve incommentAnalysis.answer.citations. Always a job, in theanalysis_searchrate class. If the writer fails, the numbers are still ready andanswer.errorexplains. - Scores over Time.
include: ["timeline"]adds the dashboard chart’s series over the matched comments, by day, week, or month, by comment date or post date, in your time zone. - Languages.
filters.languagesnarrows to comments that contain (contains) or are only in (only) the listed languages;include: ["languages"]adds a language breakdown. GET /analyses/{id}/export. Flatposts,sides,timeline,languages, andcitationstables as JSON or CSV. Thepoststable carries the same join keys as scan and match rows. Every analysis links it asexport.url.- Answers need
comments:read. Requestinganswerwithout it is a403, and a key without it that reads an analysis gets citations as ids and post links only. GET /analyses?kind=comparisonlists comparisons.- New rate classes:
posts_scan,breakdowns,posts_match(20 / minute, 500 / day each) andanalysis_export(30 / minute, 500 / day).GET /melists them underrateLimit.routeClasses.
MCP (beta)
The Analyst API is also available as an MCP, in beta, at POST /mcp on https://api.siftsy.app. Same key, same scopes, same rate classes. Tool names and shapes can still change; /analyst/v1 stays the stable warehouse contract. See MCP (beta).
1.5.2
analyses:runcan poll its own analyses.GET /analyses/{analysisId}now acceptsanalyses:runfor anan_…analysis created by the same key, so a run-only key can follow theLocationit gets back fromPOST /analyses. Listing analyses, reading another key’s analysis, or reading a saved campaign report still requiresanalyses:read. The same rule applies toGET /analyses/{analysisId}/comments, which also requirescomments:read: a key withanalyses:run+comments:readcan create, poll, and sample comments on its own analyses.GET /posts?link=answers in one page. Up to 25 links (no more thanlimit) are looked up directly, tracking parameters and trailing slashes ignored, and come back complete withhasMore: falseinstead of an empty first page. Other filters such astagwalk further per request and follow the partial-page rule below.- Collection post pages no longer time out.
GET /collections/{collectionId}/postsstops walking after a time budget and returns what it found withhasMore: true, anextCursor, andmeta.partialPage: true. A page can hold fewer thanlimitposts (even zero) whilehasMoreis true — keep followingnextCursoruntilhasMoreis false. - Older shared snapshots now load on
GET /insights. Snapshots shared before the card layout returned404 insights_not_readyeven thoughGET /snapshotslisted them. They now return their summary, topics, notable comments, and vibe check. - Absolute links. Analyses and content jobs now include
url, and everycommentsobject includescomments.urlnext tocomments.path. Both are absolute URLs on the host you called, so you can follow them without joining paths.comments.pathand theLocationheader are unchanged. GET /analyses?kind=reportworks again. It returned503 Analyses index unavailable, andkind=allsilently left saved campaign reports out. Both now list reports, newest first.- Clearer
GET /insightserror forpost_ids. Apost_idsvalue that is not on your team now returns404 One or more post_ids were not foundinstead ofSnapshot not found. expiresAtonGET /snapshotsis ISO-8601, likecreatedAt. It was previously a millisecond timestamp.
1.5.1
Your API uploads now show up in the team’s activity feed. Every team dashboard has a new Activity tab on the home panel that records what happened and where it came from — a teammate, a Siftsy Automation, or an Analyst API key. Posts added through POST /content/posts/add or POST /content/accounts/add appear as “API key “Your key name” added 12 posts to Q4 Launch”, and collections created by name through the collections field appear as “API key “Your key name” created collection …”, so a team can always tell which content was pulled in programmatically. Enterprise admins see the same rows across every sub-team on the enterprise home.
1.5.0
Refresh posts by API. POST /content/posts/refresh (posts:write) re-fetches the comments of up to 100 posts already on the team — the same as Resync in the app — by postIds and/or links. It returns a ContentJob with kind: refresh; poll it like any content job. See Adding content → Refresh posts.
Two rules, both visible on the job:
1.4.4
Base URL is now /analyst/v1. Every Analyst API path lives under https://api.siftsy.app/analyst/v1.
- New base URL:
https://api.siftsy.app/analyst/v1(local:http://localhost:3000/analyst/v1). Locationheaders use/analyst/v1/...— for example/analyst/v1/analyses/an_…and/analyst/v1/content/jobs/cj_….comments.pathis still relative to the base URL. Do not prepend/analyst/v1a second time.- The previous prefix
/v1/clientstill works as a deprecated alias. Point new integrations at/analyst/v1.
1.4.3
Renamed: Siftsy Data API → Siftsy Analyst API. Documentation only — nothing about the API itself changed.
The Analyst API helps analysts use Siftsy effectively in their workflows: import flagged content into a team (posts by URL, or a public account’s recent posts, through the content routes) and export key analyses and insights — posts, collections, scores, analyses, and saved reports — into data warehouses, data platforms, and BI tools (BI sync).
1.4.2
Post.automation— new nullable object describing how Siftsy Automations relate to a post:addedById(the automation that pulled the post in, set only whenaddedViaisautomation),ids(every automation that has added or refreshed the post),lastRefreshAtandrefreshCount(automation-driven resync history).nullwhen no automation has touched the post. This separates posts an automation added from manually added posts an automation later watches.addedByEmailfor automation-added posts is now the teammate who set up the automation (previouslynull). Posts an automation refreshes keep the original uploader’saddedByEmail.- BI sync documents the new field alongside
addedVia.
1.4.1
Documentation only — no API behavior changed.
- Adding content is a core concept, separate from the read pipeline. The Overview keeps Select → Analyze → Comments as the three-step read path and adds a distinct Adding content section for the write path (
POST /content/…→ job → posts process → readable), with its own guide card. In the sidebar it follows Retrieving comments, after the read-pipeline pages. - Adding content now walks through the ingest process end to end: the order of operations for
POST /content/posts/add(validate → target team → collections → replay → dedupe → fund check → reserve + create → queue) and forPOST /content/accounts/add(request-side steps, then discover → filter → add in a worker), plus a post-lifecycle table showing which statuses reserve, consume, or refund a credit and when a post becomes readable. The two POST operations in the API reference summarize the same order. - Authentication and the Quickstart now state the plan requirement (Powerhouse / Enterprise) and describe key management: create, rotate, revoke, scope toggles, and the usage view.
- Rate limits gains a Usage history section explaining what Team Settings → API shows and how it relates to the daily budgets.
Post.addedViais fully enumerated in the reference:dashboard,api, orautomation(posts pulled in by a Siftsy Automation on a schedule). Previouslyautomationwas returned but not listed. BI sync documents the field alongsideaddedByEmail.- The API reference description notes the plan requirement.
1.4.0
Content routes. Keys can now add content to a team the same way Add New works in the Siftsy app — same credits, same processing, programmatically. See Adding content.
POST /content/posts/add— add up to 100 post URLs. Each accepted link reserves one MAP or Ad Hoc credit (5 withcapture.fullRead), creates the post, and queues it. Links already on the team areskipped; unsupported hosts arerejected; neither is charged. Responds202with aContentJob.POST /content/accounts/add— add a public account’s recent posts (TikTok, Instagram, YouTube, Facebook pages, LinkedIn, X) using the app’s account filters:since,until,limit,keywords, plusminViews,minLikes, andpostType. Runs as a job (discovering→syncing).dryRun: truediscovers and prices without adding.GET /content/jobs/{jobId}andGET /content/jobs— poll a job foraccepted/skipped/rejectedlinks, per-post processing status, and a credit accounting view (reserved,settled,refunded). Jobs settle tocompleted,partial, orfailedand are kept for 30 days.- Collections by id or name.
collections: [{ "id": "…" }]or[{ "name": "…" }]; a name that matches an active collection is reused, otherwise a campaign is created (created: true). Ambiguous names return409 collection_name_ambiguouswith candidates.tagsmerge onto the posts. - Enterprise sub-teams. Enterprise keys may pass
teamIdto add content to (and spend the credits of) one of their sub-teams. - Idempotent. An identical request returns the existing job (
200,meta.replayed: true) instead of charging twice. A batch that cannot be funded at all returns402and creates nothing.
1.3.2
Key management — no change to /v1/client request or response shapes.
- Team Settings → API is live in the Siftsy app: create, rotate, and revoke keys (the secret is shown once), choose scopes per key, and see per-key usage.
- Plan availability. The Siftsy Analyst API is included on Powerhouse and Enterprise plans, including Enterprise sub-teams. Teams on other plans do not see the API tab. Existing keys are unaffected.
- Usage history. Requests and response bytes per key, per UTC day, for the last 30 days, with today / 7-day / window totals and the limits in force. Read from the same daily counters the rate limiter enforces, so it matches
X-RateLimit-Daily-*andGET /me. See Rate limits.
1.3.1
Documentation only — no API behavior changed.
- The
Postschema in the API reference now lists every field the API returns (creator,title,summary,description,tags,engagement,postedAt,createdAt,updatedAt,lastRefreshedAt), so generated clients keep them. The legacyvibeobject is documented as deprecated; usescoresandsentimentMix. GET /meandGET /insightsresponses are now fully typed in the reference.- Example payloads that showed
siftsyScoreon a 0–100 scale (71,31) are corrected to the 1–10 scale the API actually returns. AnalysiscommentAnalysis.scoresexamples now includescoreVersionandsiftsyScore. - Clarified when
POST /analysesruns as a job: onlysearchwithmode: ai(the default) or selections over 100 posts.mode: keywordstays a synchronous201snapshot. - Clarified paths:
comments.pathis relative to the base URL (…/v1/client); theLocationheader onPOST /analysesis a host path that already includes/v1/client. 409 analysis_not_readyis documented onGET /analyses/{analysisId}/comments(where it is returned) rather than onGET /posts/{postId}/analysis/comments.
1.3.0
POST /analyses— create an analysis from a content selection: acollectionId, explicitpostIds, orpostsfilters (the same filters asGET /posts, including the newtag). Optionally narrow the comments with dashboardfilters(mix-bar buckets, keywords, usernames, creator, replies, questions, mentions, emoji,minLikes, date range) or an AI / keywordsearch. Requires the newanalyses:runscope. See Analyses.- Analyses carry a
status. Snapshots of up to 100 posts compute inline and return201 ready; AI searches and larger selections return202 queuedwithLocationandRetry-After, then move throughrunningtoreadyorfailedonGET /analyses/{analysisId}. Analyses expire after 7 days. GET /analyses/{analysisId}/commentsapplies the analysis’s ownfilters/searchfirst for API-created analyses, returns409 analysis_not_readyuntil the analysis isready, and still accepts the mix-bar query filters andsource=sampling.GET /analysesmerges API-created analyses with saved campaign reports; filter withkind=snapshot|search|report|all. Every row carrieskindandstatus.- New post filter
tagonGET /posts,GET /collections/{collectionId}/posts, andselection.posts(case-insensitive, leading#optional, comma list matches any). - Full analysis payloads are now documented end to end: Post analysis includes a complete
GET /posts/{postId}/analysisresponse, and the API reference carries full examples forPostAnalysisandAnalysis. - Rate limits re-sized for scheduled BI refreshes. Burst caps are now sized so a sequential refresh loop cannot trip them, and per-day budgets fit eight full refreshes a day of a 500-post workspace (the Power BI Pro scheduler maximum), or one full refresh plus hourly incrementals. Global cap is 300 requests / minute and 10,000 / day per key (was 120 / minute with no daily request budget). Expensive routes have class budgets with both a burst and a daily cap:
comments(per-post sample) 120 / min · 1,000 / day,analysis_comments(GET /analyses/{id}/comments) 20 / min · 300 / day,collection_posts60 / min · 1,000 / day,analysis_read60 / min · 2,000 / day,analysis_create10 / min · 100 / day,analysis_search(AI) 2 / min · 10 / day. Daily transfer cap raised from 50 MB to 500 MB. New headersX-RateLimit-Daily-Limit,X-RateLimit-Daily-Remaining,X-RateLimit-Class,X-RateLimit-Class-Limit;GET /mereportsremainingDailyRequestsandrouteClasses.pollAfterMsfor analysis jobs is now 3000. See Rate limits for the worked BI budget. - The overview now lays out the API as selection → analysis → comments, with new core-concept explainers for Content selection and Analyses (including a worked Dove brand + influencer example).
1.2.0
- New post filters on
GET /postsandGET /collections/{collectionId}/posts:link,account,posted_until,min_score/max_score, andmin_*_percent/max_*_percentfor each sentiment bucket (positive,lean_positive,neutral,lean_negative,negative). See Filtering posts. GET /posts/{postId}/analysisreturns content + comment analysis. Comments for that analysis areGET /posts/{postId}/analysis/comments. Campaign reports use the same nesting:GET /analyses/{analysisId}/comments, for analyses of up to 1,000 posts. Mix-bar filters (sentiment,content,topic,relevance,consensus). See Post analysis and Retrieving comments.GET /posts/{postId}/metricsalso returnscontentandtopicmix bars for score version 2+.platformnow accepts a comma-separated list (platform=instagram,tiktok).linkandaccountaccept lists too.GET /collections/{collectionId}/postsnow supportsplatform,posted_since, andupdated_sinceas well.- Post list responses echo the active filters in
meta.filters. - Invalid filter values (bad dates, out-of-range numbers,
mingreater thanmax) now return400with a descriptive message. Previously an invalidupdated_sincewas silently ignored.
1.1.0
- Breaking: post payload renames
groupIds→collectionIds. - Breaking:
GET /postsnow defaults to completed posts (was: all statuses merged). Usestatus=allfor prior behavior. - New endpoints:
GET /team,GET /collections,GET /collections/{id},GET /collections/{id}/posts,GET /posts/{id}/metrics,GET /snapshots. - New scopes:
collections:read,team:read(rotate existing keys to pick them up). - Post payload additions:
scores,sentimentMix,totalComments,thumbnail,postType,addedByEmail,lastProcessedAt. - New
GET /postsfilters:status,collection_id,platform,posted_since.
