Your own Grok Bot checks your social media accounts and sends the numbers to your Soulfy workspace, where they appear on your iBrand Board. This page is written for you and for your bot.
In your dashboard, open your workspace's Grok Bot Connection page and click Create connect code. Paste the message it gives you into your Grok chat. The code (sfc_…) works once and expires after 15 minutes, so it is safe even if it stays in chat history. Grok exchanges it for its own credential:
Reply (HTTP 201). The token is shown only this once:
The bot must store token as a secret named SOULFY_AGENT_TOKEN and never show it in chat. Lost it? Click Rotate on the connection page for a fresh code.
Returns the workspace, granted permissions and when the credential expires. Nothing is saved.
Needs the Read iBrand permission (ibrand.read), which a new connection has. Every Bio Link uses this same API. The credential is bound to one Bio Link, and the reply is that Bio Link's Board: overview totals, earnings, each platform's metrics, the current and previous date ranges, and last-sync times. A platform is marked stale when its latest measurement is old. connections lists this workspace's Grok Bot connections (status and last use; never a token). weekly_plan is the owner's Weekly Growth Plan for the week when they have one, and null when they don't.
Overview cards are the cross-platform totals. Soulfy stores observed readings, so the reply has no overall score and no 7UP score field.
A shortened reply. board is the full dashboard view model; metric rows, earnings and charts are included.
period is 7, 30 (the default) or 90. Or send from and to as YYYY-MM-DD. week picks the Weekly Growth Plan week. workspace, if you send it, must be this site's domain.
The measurements behind those figures, newest first and in the same shape as the Board's recent list: GET https://soulfy.com/api/agent/v1/ibrand/history. Optional limit (1–100, default 50), platform, and the same period parameters.
| Field | Required | Notes |
|---|---|---|
platform | yes | One of instagram facebook linkedin tiktok youtube x spotify substack stripe |
captured_at | yes | ISO 8601 with a timezone, e.g. 2026-09-29T21:10:00+08:00. Up to a year old. |
metrics | yes | Object of lowercase_snake_case names to numbers (up to 50). Use the names below. |
collection_method | no | One of browser_agent platform_export manual_entry other (default browser_agent) |
source, evidence | no | Flat objects of strings, e.g. profile_url, screenshot_url |
workspace | no | Your site domain. Must match the credential. |
Example:
Success (HTTP 201):
Test without saving: send the same request to https://soulfy.com/api/agent/v1/measurements?dry_run=true. You get HTTP 200 with dry_run: true, exactly what would be stored, and any warnings.
Send every earnings figure a platform shows, in the same snapshot as the other metrics. The iBrand Board shows estimated_earnings as each platform's headline number, in large type at the top. With any earnings, add "source": {"currency": "<ISO code as shown, e.g. USD>", "earnings_period": "<the period the platform shows, e.g. last_28_days or this_month>"}. Amounts are shown exactly as reported: never convert currencies, estimate, or send a figure the platform doesn't show.
| Platform | Where | Platform figure → metric name |
|---|---|---|
| Professional dashboard or Meta Business Suite, Monetization |
| |
| Professional dashboard, Monetization |
| |
| YouTube | YouTube Studio, Analytics, Revenue (or Earn) |
|
| TikTok | TikTok Studio, Rewards or Creator Rewards Program |
|
| X | Monetization, Creator Revenue Sharing and Subscriptions |
|
| Usually no creator earnings. Send them only if LinkedIn shows an earnings figure. |
| |
| Spotify | Spotify for Artists (or Spotify for Podcasters), Audience and Lifetime / earnings if shown |
|
| Substack | Substack Dashboard, Stats and Payments / Earnings |
|
If two platforms report the same currency and the same period, the Board also shows their combined total. Otherwise each platform stands on its own.
Send Stripe figures as platform: "stripe" — one snapshot per currency per day. Amounts are major units (not cents). They appear as Stripe · Sales cards and are never added to creator earnings. Money metrics require source.currency and source.earnings_period (enforced for stripe).
| Platform | Where | Platform figure → metric name |
|---|---|---|
| Stripe | Stripe Dashboard: Home, Payments, Billing/Subscriptions |
|
Use these names so each number lands in the right chart. Board overview metrics are also combined across platforms. Any other name is still saved, shown under "Other reported metrics", and the reply includes a warnings entry with the closest recommended name.
| Platform | Metrics |
|---|---|
| |
| |
| |
| TikTok |
|
| YouTube |
|
| X |
|
| Spotify |
|
| Substack |
|
| Stripe |
|
Use only real numbers the bot collected. Never estimate or invent values.
When the owner clicks Execute on a Growth Action, Soulfy places a job in a queue for your bot. The bot needs the Run Growth Actions permission, which the owner turns on at the Grok Bot Connection page; new connections don't get it automatically. Jobs are pulled by the bot; Soulfy never pushes to it. The bot prepares drafts and checklists only. It never publishes, posts, replies or sends anything, and asks the owner instead of guessing.
GET https://soulfy.com/api/agent/v1/growth/jobs. Jobs you're working on come first (claimed_by_you: true), then the queue.POST https://soulfy.com/api/agent/v1/growth/jobs/{id}/claim. The reply holds instructions, execution_rules, the action, focus, goal, and the owner's niche and the action's topic (each null when not set). Follow the execution rules. If another bot claimed it first you get 409; pick the next.POST …/results with {"result_type": "draft", "data": {"text": "…"}, "summary": "…"}. Types: draft text checklist external_reference artifact status POST …/questions with {"input_type": "choice", "prompt": "…", "options": ["A", "B"]}. The job waits; poll GET …/{id} until its status is RUNNING again and read the answer in questions. Never ask for passwords, keys or other credentials.POST …/heartbeat keeps the job yours.POST …/complete (optionally {"result": {…}}) or POST …/fail with {"reason": "…"}. If the owner cancels, the job's status becomes CANCELLED and further writes return 409, so stop work.Cadence. Send one snapshot per platform after each daily stats check. Once a day is plenty; the Board shows change over days and weeks.
Rate limits
Retries and duplicates
Every error is JSON: {"success": false, "code": "…", "error": "…"}. A GET to https://soulfy.com/api/agent/v1/measurements or https://soulfy.com/api/agent/v1/connect returns the request format instead of an empty 405, and https://soulfy.com/api/agent/v1 lists every endpoint.
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON. |
| 400 | invalid_platform | platform is missing or not one of instagram, facebook, linkedin, tiktok, youtube, x, spotify, substack, stripe. |
| 400 | invalid_captured_at | captured_at is missing, has no timezone, is in the future, or is over a year old. |
| 400 | invalid_metrics | metrics isn't an object, a name isn't lowercase snake_case, or a value isn't a finite number. |
| 400 | invalid_note | note isn't plain text, or is longer than 1000 characters after normalising. |
| 400 | invalid_metadata | Money metrics need source.currency (3-letter ISO 4217) and source.earnings_period. Enforced for stripe; other platforms get warnings for now. |
| 400 | unknown_field | The body has a top-level field the API doesn't accept. |
| 400 | invalid_request | A Growth Actions body field is missing or invalid, too large, or looks like a credential. |
| 400 | invalid_connect_code | The connect code is wrong, already used, or expired. Ask the owner for a new one. |
| 401 | unauthorized | The Authorization: Bearer header is missing, or the credential is invalid, expired or revoked. |
| 403 | insufficient_scope | The connection doesn't have the permission this endpoint needs. |
| 403 | workspace_mismatch | The body's workspace field names a different site. |
| 403 | custom_domain_required | The site isn't live on its own domain yet. |
| 403 | workspace_inactive | The workspace is suspended or cancelled. |
| 403 | forbidden | Another connection claimed this Growth Actions job. |
| 404 | not_found | No such Growth Actions job for this workspace, or it isn't queued or yours. |
| 405 | method_not_allowed | Wrong HTTP method. The reply lists the allowed methods. |
| 409 | idempotency_conflict | The Idempotency-Key was already used for different data. |
| 409 | invalid_transition | The job's status doesn't allow that, e.g. it was cancelled, already claimed or expired. GET the job to see its status. |
| 409 | conflict | The job changed at the same moment. GET it and try again. |
| 413 | payload_too_large | The body is over 16 KB. |
| 415 | unsupported_media_type | Content-Type isn't application/json. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |