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.

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