Skip to content
BuzzTake
Sign inGet started
MenuClose
DocumentationQuickstart

Quickstart

Add an account, then act through it. Four calls.

Before you start

Create an API key in the web app. Set the key and your workspace id.

Shell
export BUZZTAKE_API_KEY="btk1_..."
export WORKSPACE_ID="0199..."

1. Add an account

POST/v1/workspaces/{workspace_id}/accounts

Send the password and the 2FA secret. BuzzTake signs in and answers 2FA codes itself. The proxy is optional.

Request
curl https://api.buzztake.com/v1/workspaces/$WORKSPACE_ID/accounts \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "x",
    "label": "Brand main",
    "connect": {
      "method": "password",
      "username": "acme_demo",
      "password": "your-password",
      "totp_secret": "JBSWY3DPEHPK3PXP"
    },
    "proxy": "http://user:pass@203.0.113.7:8000"
  }'
201 Created (trimmed)
{
  "account": {
    "id": "0199a1b2-...",
    "platform": "x",
    "label": "Brand main",
    "status": "connecting",
    "has_credentials": true
  },
  "action": {
    "id": "0199c3d4-...",
    "type": "connect",
    "status": "queued",
    "credits": 25
  }
}

The connect action signs in. With method: browser, or when a challenge appears, the answer also carries a sign_in_url. Save account.id as $ACCOUNT_ID.

2. Run an action

POST/v1/accounts/{id}/actions

wait holds the request up to that many seconds (max 120). Idempotency-Key makes a retry safe.

Request
curl https://api.buzztake.com/v1/accounts/$ACCOUNT_ID/actions \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-1" \
  -d '{ "type": "post", "text": "Dark mode is live.", "wait": 60 }'
200 OK
{
  "id": "0199e5f6-...",
  "account_id": "0199a1b2-...",
  "type": "post",
  "status": "succeeded",
  "params": { "text": "Dark mode is live." },
  "result": { "type": "created", "url": "https://x.com/acme_demo/status/1", "id": "1" },
  "error": null,
  "challenge": null,
  "credits": 10,
  "created_at": "2026-10-14T09:00:00Z",
  "started_at": "2026-10-14T09:00:01Z",
  "finished_at": "2026-10-14T09:00:09Z"
}

Not finished inside wait: you get 202 and the same object. Poll GET /v1/actions/{id}?wait=30.

3. Answer a challenge

When the platform asks for a code, the action stops at needs_input.

Action waiting for input (trimmed)
{
  "id": "0199c3d4-...",
  "type": "connect",
  "status": "needs_input",
  "challenge": {
    "kind": "email_code",
    "message": "Enter the code the platform sent by email.",
    "expires_at": "2026-10-14T09:10:00Z",
    "sign_in_url": "https://buzztake.com/connect/bts_..."
  }
}

POST/v1/actions/{id}/answer

Answer, then wait for the result
curl -X POST https://api.buzztake.com/v1/actions/$ACTION_ID/answer \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "123456" }'

curl "https://api.buzztake.com/v1/actions/$ACTION_ID?wait=30" \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY"

Or open sign_in_url and finish in the live browser. It works for 30 minutes, without a BuzzTake login, so you can send it to the account owner.

4. Post with media

POST/v1/workspaces/{workspace_id}/media

Upload the file, then pass its id in media.

Upload launch.png
# 1. Ask for an upload
curl https://api.buzztake.com/v1/workspaces/$WORKSPACE_ID/media \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"launch.png\",
    \"mime_type\": \"image/png\",
    \"bytes\": $(wc -c < launch.png | tr -d ' '),
    \"checksum_sha256\": \"$(shasum -a 256 launch.png | cut -d ' ' -f 1)\"
  }"

# 2. Send the file to upload_url, with every header in required_headers
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @launch.png

# 3. Finish the upload
curl -X POST "https://api.buzztake.com$FINALIZE_URL" \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY"
201 Created (trimmed)
{
  "outcome": "upload_required",
  "asset": { "id": "0199f7a8-...", "mime_type": "image/png" },
  "upload_url": "https://...",
  "required_headers": { "...": "..." },
  "finalize_url": "/v1/workspaces/0199.../media/0199f7a8-.../finalize"
}

outcome: already_present means the workspace has this file. Use asset.id and skip steps 2 and 3.

Post with the image
curl https://api.buzztake.com/v1/accounts/$ACCOUNT_ID/actions \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "post", "text": "Launch day.", "media": ["0199f7a8-..."], "wait": 60 }'

Next

  • Accounts: connect methods, statuses, sign-in links.
  • Actions: every type, parameter and price.
  • MCP server: give the same accounts to your agent.