> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.siftsy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.siftsy.com/_mcp/server.

# Changelog

## September 28, 2026

## 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](/guides/core-concepts/exploring).

* **`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)](/guides/get-started/mcp).

## September 23, 2026

## 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.

## September 17, 2026

## 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.

Team members can opt in to email notifications about this activity (any change, automations only, or off) from **Team Settings → Notifications**. Notifications are separate from Monitoring API alerts and do not change any API response.

No request or response shape changed. The API key's `name` is what the feed shows — give keys descriptive names.

## September 16, 2026

## 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](/guides/core-concepts/adding-content#refresh-posts-already-on-the-team).

Two rules, both visible on the job:

* **12-hour floor.** A given post on a given team is refreshed at most once every 12 hours through the API and through Siftsy Automations. Posts refreshed more recently are `skipped` with `reason: min_interval` and a `nextRefreshAt`, and are never charged. `minRefreshIntervalHours: 12` is on every refresh job.
* **Same credits as the app.** A refresh is free (`creditSource: included`, `creditCost: 0`) when the plan's included refresh cadence allows it; otherwise it spends one MAP or Ad Hoc credit (`creditSource: credit`), five with `capture.fullRead`. There is no separate refresh credit. `credits.included` counts the free ones; `credits.reserved` / `settled` / `refunded` sum the charged ones.

Also:

* New rate class `content_refresh` (10 / minute, 200 / day per key), listed under `rateLimit.routeClasses` on `GET /me`.
* `ContentJobLinkResult` gains `creditSource`, `creditCost`, `dataVersion`, and `nextRefreshAt` (refresh jobs only). New `reason` values: `min_interval`, `cooldown`, `not_found`, `not_on_team`, `unreachable`.
* Identical refresh requests are not replayed (unlike `POST /content/posts/add`); the floor already makes a repeat call free.
* **Siftsy Automations** (in the app) now follow the same 12-hour floor: Live Monitor's minimum cadence is `12h` (previously `1h`, default `2h`), and Lifecycle Refresh will not refresh a post within 12 hours of its last processing. Existing monitors with a shorter cadence keep running but fire at most every 12 hours.

## 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](/guides/core-concepts/adding-content)) and **export key analyses and insights** — posts, collections, scores, analyses, and saved reports — into data warehouses, data platforms, and BI tools ([BI sync](/guides/core-concepts/bi-sync)).

* Base URL (`/v1/client`), endpoints, scopes, key prefixes (`sk_live_` / `sk_test_`), headers, rate limits, and response shapes are unchanged. Existing keys and integrations keep working with no action.
* The [Overview](/guides/get-started/overview) is rewritten around the import → analyze → export workflow.

## September 15, 2026

## 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](/guides/core-concepts/bi-sync) documents the new field alongside `addedVia`.

## September 14, 2026

## 1.4.1

Documentation only — no API behavior changed.

* **Adding content is a core concept, separate from the read pipeline.** The [Overview](/guides/get-started/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](/guides/core-concepts/adding-content#how-adding-content-works) 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](/guides/core-concepts/authentication) and the [Quickstart](/guides/get-started/quickstart) now state the plan requirement (Powerhouse / Enterprise) and describe key management: create, rotate, revoke, scope toggles, and the usage view.
* [Rate limits](/guides/core-concepts/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](/guides/core-concepts/bi-sync) documents the field alongside `addedByEmail`.
* The API reference description notes the plan requirement.

## September 13, 2026

## 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](/guides/core-concepts/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.

**Scopes.** Two new, **opt-in** scopes: `posts:write` and `accounts:write`. They are not granted by default; a team admin enables them per key in **Team Settings → API**. Existing keys are unchanged and cannot add content until rotated with the new scopes.

**Rate limits.** New classes `content_add_posts` (10/min, 200/day), `content_add_accounts` (2/min, 20/day), and `content_jobs` (60/min, 2,000/day). `GET /me` lists them under `rateLimit.routeClasses`.

**Posts.** `Post.addedVia` is `api` for posts created through the content routes and `dashboard` otherwise. Posts added through the API also appear in the app for the team, like any upload.

## September 12, 2026

## 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](/guides/core-concepts/rate-limits#usage-history).

## September 11, 2026

## 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`.

## September 10, 2026

## 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](/guides/core-concepts/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](/guides/core-concepts/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](/guides/core-concepts/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](/guides/core-concepts/content-selection) and [Analyses](/guides/core-concepts/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](/guides/core-concepts/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](/guides/core-concepts/post-analysis) and [Retrieving comments](/guides/core-concepts/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.

## August 1, 2026

## 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`.