Skip to navigation

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 as matched, processing, failed, not_in_workspace, invalid_url, or unsupported_platform, and meta.matchedPostIds drops straight into selection.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 /analyses takes compare — 2 to 4 labeled selections — instead of selection. Each side gets its own scope, content, and comment analysis; comparison.deltas gives each side against side 1. GET /analyses/{id}/comments?side=N samples one side.
  • Cited answers. answer: { question } (or answer: true for an overview) writes the finding in words, with every claim citing real comments that resolve in commentAnalysis.answer.citations. Always a job, in the analysis_search rate class. If the writer fails, the numbers are still ready and answer.error explains.
  • 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.languages narrows to comments that contain (contains) or are only in (only) the listed languages; include: ["languages"] adds a language breakdown.
  • GET /analyses/{id}/export. Flat posts, sides, timeline, languages, and citations tables as JSON or CSV. The posts table carries the same join keys as scan and match rows. Every analysis links it as export.url.
  • Answers need comments:read. Requesting answer without it is a 403, and a key without it that reads an analysis gets citations as ids and post links only.
  • GET /analyses?kind=comparison lists comparisons.
  • New rate classes: posts_scan, breakdowns, posts_match (20 / minute, 500 / day each) and analysis_export (30 / minute, 500 / day). GET /me lists them under rateLimit.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:run can poll its own analyses. GET /analyses/{analysisId} now accepts analyses:run for an an_… analysis created by the same key, so a run-only key can follow the Location it gets back from POST /analyses. Listing analyses, reading another key’s analysis, or reading a saved campaign report still requires analyses:read. The same rule applies to GET /analyses/{analysisId}/comments, which also requires comments:read: a key with analyses:run + comments:read can create, poll, and sample comments on its own analyses.
  • GET /posts?link= answers in one page. Up to 25 links (no more than limit) are looked up directly, tracking parameters and trailing slashes ignored, and come back complete with hasMore: false instead of an empty first page. Other filters such as tag walk further per request and follow the partial-page rule below.
  • Collection post pages no longer time out. GET /collections/{collectionId}/posts stops walking after a time budget and returns what it found with hasMore: true, a nextCursor, and meta.partialPage: true. A page can hold fewer than limit posts (even zero) while hasMore is true — keep following nextCursor until hasMore is false.
  • Older shared snapshots now load on GET /insights. Snapshots shared before the card layout returned 404 insights_not_ready even though GET /snapshots listed them. They now return their summary, topics, notable comments, and vibe check.
  • Absolute links. Analyses and content jobs now include url, and every comments object includes comments.url next to comments.path. Both are absolute URLs on the host you called, so you can follow them without joining paths. comments.path and the Location header are unchanged.
  • GET /analyses?kind=report works again. It returned 503 Analyses index unavailable, and kind=all silently left saved campaign reports out. Both now list reports, newest first.
  • Clearer GET /insights error for post_ids. A post_ids value that is not on your team now returns 404 One or more post_ids were not found instead of Snapshot not found.
  • expiresAt on GET /snapshots is ISO-8601, like createdAt. 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).
  • Location headers use /analyst/v1/... — for example /analyst/v1/analyses/an_… and /analyst/v1/content/jobs/cj_….
  • comments.path is still relative to the base URL. Do not prepend /analyst/v1 a second time.
  • The previous prefix /v1/client still 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 when addedVia is automation), ids (every automation that has added or refreshed the post), lastRefreshAt and refreshCount (automation-driven resync history). null when no automation has touched the post. This separates posts an automation added from manually added posts an automation later watches.
  • addedByEmail for automation-added posts is now the teammate who set up the automation (previously null). Posts an automation refreshes keep the original uploader’s addedByEmail.
  • 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 for POST /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.addedVia is fully enumerated in the reference: dashboard, api, or automation (posts pulled in by a Siftsy Automation on a schedule). Previously automation was returned but not listed. BI sync documents the field alongside addedByEmail.
  • 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 with capture.fullRead), creates the post, and queues it. Links already on the team are skipped; unsupported hosts are rejected; neither is charged. Responds 202 with a ContentJob.
  • 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, plus minViews, minLikes, and postType. Runs as a job (discovering → syncing). dryRun: true discovers and prices without adding.
  • GET /content/jobs/{jobId} and GET /content/jobs — poll a job for accepted / skipped / rejected links, per-post processing status, and a credit accounting view (reserved, settled, refunded). Jobs settle to completed, partial, or failed and 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 return 409 collection_name_ambiguous with candidates. tags merge onto the posts.
  • Enterprise sub-teams. Enterprise keys may pass teamId to 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 returns 402 and 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-* and GET /me. See Rate limits.

1.3.1

Documentation only — no API behavior changed.

  • The Post schema 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 legacy vibe object is documented as deprecated; use scores and sentimentMix.
  • GET /me and GET /insights responses are now fully typed in the reference.
  • Example payloads that showed siftsyScore on a 0–100 scale (71, 31) are corrected to the 1–10 scale the API actually returns. Analysis commentAnalysis.scores examples now include scoreVersion and siftsyScore.
  • Clarified when POST /analyses runs as a job: only search with mode: ai (the default) or selections over 100 posts. mode: keyword stays a synchronous 201 snapshot.
  • Clarified paths: comments.path is relative to the base URL (…/v1/client); the Location header on POST /analyses is a host path that already includes /v1/client.
  • 409 analysis_not_ready is documented on GET /analyses/{analysisId}/comments (where it is returned) rather than on GET /posts/{postId}/analysis/comments.

1.3.0

  • POST /analyses — create an analysis from a content selection: a collectionId, explicit postIds, or posts filters (the same filters as GET /posts, including the new tag). Optionally narrow the comments with dashboard filters (mix-bar buckets, keywords, usernames, creator, replies, questions, mentions, emoji, minLikes, date range) or an AI / keyword search. Requires the new analyses:run scope. See Analyses.
  • Analyses carry a status. Snapshots of up to 100 posts compute inline and return 201 ready; AI searches and larger selections return 202 queued with Location and Retry-After, then move through running to ready or failed on GET /analyses/{analysisId}. Analyses expire after 7 days.
  • GET /analyses/{analysisId}/comments applies the analysis’s own filters / search first for API-created analyses, returns 409 analysis_not_ready until the analysis is ready, and still accepts the mix-bar query filters and source= sampling.
  • GET /analyses merges API-created analyses with saved campaign reports; filter with kind=snapshot|search|report|all. Every row carries kind and status.
  • New post filter tag on GET /posts, GET /collections/{collectionId}/posts, and selection.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}/analysis response, and the API reference carries full examples for PostAnalysis and Analysis.
  • 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_posts 60 / min · 1,000 / day, analysis_read 60 / min · 2,000 / day, analysis_create 10 / min · 100 / day, analysis_search (AI) 2 / min · 10 / day. Daily transfer cap raised from 50 MB to 500 MB. New headers X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining, X-RateLimit-Class, X-RateLimit-Class-Limit; GET /me reports remainingDailyRequests and routeClasses. pollAfterMs for 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 /posts and GET /collections/{collectionId}/posts: link, account, posted_until, min_score / max_score, and min_*_percent / max_*_percent for each sentiment bucket (positive, lean_positive, neutral, lean_negative, negative). See Filtering posts.
  • GET /posts/{postId}/analysis returns content + comment analysis. Comments for that analysis are GET /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}/metrics also returns content and topic mix bars for score version 2+.
  • platform now accepts a comma-separated list (platform=instagram,tiktok). link and account accept lists too.
  • GET /collections/{collectionId}/posts now supports platform, posted_since, and updated_since as well.
  • Post list responses echo the active filters in meta.filters.
  • Invalid filter values (bad dates, out-of-range numbers, min greater than max) now return 400 with a descriptive message. Previously an invalid updated_since was silently ignored.

1.1.0

  • Breaking: post payload renames groupIds → collectionIds.
  • Breaking: GET /posts now defaults to completed posts (was: all statuses merged). Use status=all for 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 /posts filters: status, collection_id, platform, posted_since.
breaking-change