Changelog

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.

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:

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.

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

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

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.

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.

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.

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.

• 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).

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

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