Grok Bot API

1. Connect with a one-time code

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:

POST https://soulfy.com/api/agent/v1/connect
Content-Type: application/json

{"code": "sfc_…"}

Reply (HTTP 201). The token is shown only this once:

{
  "success": true,
  "token": "sfa_…",
  "token_type": "Bearer",
  "workspace": {
    "name": "Your brand",
    "site_domain": "yourbrand.com"
  },
  "scopes": [
    "measurements.write"
  ],
  "expires_at": "2027-09-30T00:00:00.000Z",
  "endpoints": {
    "me": "https://soulfy.com/api/agent/v1/me",
    "measurements": "https://soulfy.com/api/agent/v1/measurements",
    "dry_run": "https://soulfy.com/api/agent/v1/measurements?dry_run=true"
  },
  "instructions": [
    "…"
  ]
}

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.

2. Check the connection

GET https://soulfy.com/api/agent/v1/me
Authorization: Bearer $SOULFY_AGENT_TOKEN

Returns the workspace, granted permissions and when the credential expires. Nothing is saved.

Read the iBrand Board

Needs the Read iBrand permission (ibrand.read), which a new connection has. Every microsite uses this same API. The credential is bound to one site, and the reply is that site'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.

GET https://soulfy.com/api/agent/v1/ibrand/board?period=30
Authorization: Bearer $SOULFY_AGENT_TOKEN

A shortened reply. board is the full dashboard view model; metric rows, earnings and charts are included.

{
  "success": true,
  "workspace": { "name": "Alpha Studio", "domain": "alpha.soulfy.com", "site_domain": "alpha-brand.com" },
  "period": { "kind": "preset", "days": 30, "error": null },
  "truncated": false,
  "board": {
    "hasData": true,
    "window": { "start": "2026-09-14T06:00:00.000Z", "end": "2026-10-14T06:05:00.000Z" },
    "previousWindow": { "start": "2026-08-15T06:00:00.000Z", "end": "2026-09-14T06:00:00.000Z" },
    "lastCapturedAt": "2026-10-13T09:00:00.000Z",
    "lastReceivedAt": "2026-10-13T09:00:04.000Z",
    "platforms": [{ "platform": "instagram", "label": "Instagram", "freshness": { "lastCapturedAt": "2026-10-13T09:00:00.000Z", "stale": false, "collectionMethod": "Grok Bot" } }]
  },
  "connections": [{ "provider": "grok", "display_name": "Alpha agent", "status": "active", "last_used_at": "2026-10-14T06:00:00.000Z", "expires_at": null, "this_connection": true }],
  "weekly_plan": null
}

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.

3. Send a snapshot

POST https://soulfy.com/api/agent/v1/measurements
Authorization: Bearer $SOULFY_AGENT_TOKEN
Content-Type: application/json
Idempotency-Key: optional

Example:

curl -X POST "https://soulfy.com/api/agent/v1/measurements" \
  -H "Authorization: Bearer $SOULFY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "captured_at": "2026-09-29T21:10:00+08:00",
    "metrics": {
      "estimated_earnings": 125.4,
      "content_monetization_earnings": 98.1,
      "followers": 5517,
      "reach": 4001,
      "reactions": 46,
      "comments": 15,
      "shares": 15
    },
    "source": {
      "currency": "USD",
      "earnings_period": "last_28_days"
    }
  }'

Success (HTTP 201):

{
  "success": true,
  "measurement_id": "5b7f0c1e-…",
  "platform": "instagram",
  "captured_at": "2026-09-29T13:10:00.000Z",
  "received_at": "2026-09-30T00:03:59.858Z",
  "idempotent_replay": false,
  "warnings": [
    {
      "code": "unknown_metric",
      "metric": "follower_count",
      "suggestion": "followers",
      "message": "\"follower_count\" isn't a recommended metric name. It was saved under Other reported metrics. Did you mean \"followers\"? …"
    }
  ]
}

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.

Recommended metric names

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.

Use only real numbers the bot collected. Never estimate or invent values.

Run Growth Actions (optional)

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.

1. Every 30 seconds or slower: GET https://soulfy.com/api/agent/v1/growth/jobs. Jobs you're working on come first (claimed_by_you: true), then the queue.
2. Claim one: 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.
3. Add results as you go: POST …/results with {"result_type": "draft", "data": {"text": "…"}, "summary": "…"}. Types: draft text checklist external_reference artifact status
4. Need a decision? 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.
5. Working longer than 30 minutes? POST …/heartbeat keeps the job yours.
6. Finish with 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.

How often, limits and retries

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

• 60 requests per 10 minutes per connection, per endpoint.
• 300 requests per 60 minutes per workspace, per endpoint, across all its connections.
• 20 failed sign-ins (bad credential or connect code) per 10 minutes per IP address.
• Over a limit you get HTTP 429 with a Retry-After header (seconds).

Retries and duplicates

• Send an optional Idempotency-Key header (1-128 characters of A-Z a-z 0-9 . _ : -) to make retries safe.
• Without one, the key is a fingerprint of platform, captured_at, collection_method, metrics, source and evidence, so resending the exact same snapshot never creates a duplicate.
• A repeat with the same key and the same data returns HTTP 200 with the original measurement_id and idempotent_replay: true.
• The same key with different data returns HTTP 409 idempotency_conflict.

Errors

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.

Standing instructions for your Grok Bot

1. Keep the credential secret as SOULFY_AGENT_TOKEN. Never paste it into chat.
2. Send it as "Authorization: Bearer <token>" with "Content-Type: application/json".
3. Send one snapshot per platform after each daily stats check. Once a day is plenty; the Board shows change over days and weeks. POST to https://soulfy.com/api/agent/v1/measurements.
4. Body: {"platform", "captured_at" (ISO 8601 with timezone), "metrics": {name: number}}.
5. Use the recommended metric names at https://soulfy.com/docs/grok-bot; unknown names are saved but not charted.
6. Include monetization earnings wherever a platform shows them: estimated_earnings for the platform's headline figure (Facebook Approximate earnings, YouTube Estimated revenue, TikTok Estimated rewards, X Creator revenue sharing, Substack earnings, Spotify royalties when shown), plus content_monetization_earnings, ad_earnings, subscription_earnings, fan_support_earnings and bonus_earnings when shown.
7. 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>"}.
8. Use only real numbers you collected. Never estimate, convert or invent values.
9. Add ?dry_run=true to check a request without saving it.
10. Read the iBrand Board those snapshots build with GET https://soulfy.com/api/agent/v1/ibrand/board (needs ibrand.read). It matches the Board the owner sees: overview totals, per-platform metrics, date ranges and last-sync times. GET https://soulfy.com/api/agent/v1/ibrand/history lists the measurements behind it.
11. If the owner gave you the Run Growth Actions permission: GET https://soulfy.com/api/agent/v1/growth/jobs no more than every 30 seconds, claim a job with POST https://soulfy.com/api/agent/v1/growth/jobs/{id}/claim, and follow its instructions and execution_rules. Post drafts to .../results, ask the owner through .../questions instead of guessing, and finish with .../complete or .../fail. Never publish, post, reply or send anything yourself.