Reference
Four Bearer-authenticated endpoints for the Agency plan. Read-only today — writes remain in the dashboard. Shapes are hand-verified against the backing Pydantic schemas, never auto-generated from a spec that could drift.
Mint a token in the dashboard under Settings → Agency → API tokens. Each token is scoped to a single Agency workspace and one or more fine-grained scopes (trends:read, briefs:read, performance:read). Tokens are shown once at creation — store them in your secrets manager, not in source.
Authorization: Bearer <your-token>Every endpoint requires a single scope. Requests with a token missing the required scope return 403 Forbidden with detail: api_scope_required. Grant only the scopes a given integration needs.
{ detail: string, code: string }Rate-limited requests return 429 Too Many Requests with a Retry-After header. Missing-scope requests return 403. Missing or revoked tokens return 401.
Returns trends whose status is `rising` or `peaking`, ranked by virality score descending then by first-seen-at descending. If `niche` is omitted, defaults to the workspace's first tracked niche (configured at account creation).
nichequerystringoptionalFilter to a specific niche slug (e.g. `microsaas`, `algotrading`). Defaults to the workspace's first tracked niche.
limitqueryinteger (1–100)optionalMaximum number of trends to return. Default 25.
Array of TrendOut — each with the four-factor score breakdown hydrated.
iduuidStable trend identifier
platformenum: tiktok | youtube | instagramSource platform
nichestringNiche slug this trend belongs to
keywordstringShort phrase describing the trend
virality_scoreinteger (0–100)Composite score. See /#methodology for the weight breakdown.
saturation_scoreinteger (0–100)How crowded the trend already is — higher means more creators have joined.
content_window_hoursintegerEstimated hours before the trend peaks. Inversely correlated with score — a high-score trend has a tighter window (post now) while a lower-score trend has more room.
statusenum: rising | peaking | fading | deadLifecycle stage. Agency endpoints return only `rising` and `peaking`.
views_per_hourintegerCross-platform view velocity
engagement_ratefloat (0–1)Mean engagement rate across sampled posts
creator_countintegerDistinct creators posting this trend
first_seen_atdatetime (ISO 8601)When BIMBAS first detected this trend
score_breakdownobject (nullable)nullablePer-factor point allocation (velocity · engagement · saturation · freshness). See TrendOut.score_breakdown in schemas/trend.py for the exact shape.
curl -sS "https://api.bimbas.io/v1/agency-api/trends?niche=microsaas&limit=10" \
-H "Authorization: Bearer \$BIMBAS_AGENCY_TOKEN"Returns a single trend with the same shape as the list endpoint. Use this to fetch the full record after selecting from the list response. 404s if the trend is not visible to your workspace.
trend_idpathuuidrequiredThe `id` field from a prior list response.
Single TrendOut — same shape as the list endpoint.
(see the list endpoint)TrendOutIdentical payload shape to /v1/agency-api/trends[].
curl -sS "https://api.bimbas.io/v1/agency-api/trends/\$TREND_ID" \
-H "Authorization: Bearer \$BIMBAS_AGENCY_TOKEN"Returns a slim summary of every brief generated by workspace members — enough to render a dashboard view without pulling the full brief body. Ordered newest first. For the full brief body (hooks, format, posting intel, hashtags), use the internal dashboard for now.
Array of AgencyBriefSummaryOut.
iduuidBrief identifier
user_iduuidWorkspace member who generated the brief
trend_iduuidThe trend this brief was generated for
platformstringSource platform of the underlying trend
virality_scoreinteger (0–100)Snapshot of the trend's score at the time of brief generation
created_atdatetime (ISO 8601)When the brief was generated
curl -sS "https://api.bimbas.io/v1/agency-api/briefs" \
-H "Authorization: Bearer \$BIMBAS_AGENCY_TOKEN"Aggregates performance_logs across all workspace members into a single summary — total tracked posts, resolved (fully-scored) posts, and mean actual vs predicted scores. Useful for rendering client-facing dashboards that show BIMBAS lift over time.
AgencyPerformanceSummaryOut.
total_logsintegerTotal performance logs across the workspace
resolved_logsintegerLogs with an `actual_performance_score` (i.e. MONITOR has scraped the 72h snapshot)
average_actual_scorefloat (nullable)nullableMean actual score across resolved logs. `null` when no resolved logs exist yet.
average_predicted_scorefloat (nullable)nullableMean predicted virality score (snapshot at brief-generation time) across the same resolved logs.
curl -sS "https://api.bimbas.io/v1/agency-api/performance/summary" \
-H "Authorization: Bearer \$BIMBAS_AGENCY_TOKEN"Agency plans include priority email support. Reach out at support@bimbas.io with your workspace name and we'll help you wire the integration. Expected response within one business day for Agency-plan clients.
Found a docs drift (response shape doesn't match what you got)? Tell us — we'll fix it same-day. The source-of-truth schemas live in apps/api/bimbas/schemas/.