Add social accounts

Saved social accounts let Reddit and X automations reference validated credentials by UUID instead of sending credentials in every automation request. Account credentials are never returned by the public REST API.

Create a Reddit account

curl --request POST \
  --url https://api.agenticscraper.com/api/v1/social-accounts \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY" \
  --data '{
    "platform": "reddit",
    "name": "Production Reddit app",
    "isActive": true,
    "credentials": {
      "redditClientId": "<reddit-client-id>",
      "redditClientSecret": "<reddit-client-secret>",
      "redditUserAgent": "my-product/1.0",
      "redditUsername": "<optional-username>",
      "redditPassword": "<optional-password>"
    }
  }'

The API requests a Reddit access token to validate the client ID and secret before saving the account.

Create an X account

curl --request POST \
  --url https://api.agenticscraper.com/api/v1/social-accounts \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY" \
  --data '{
    "platform": "x",
    "name": "Research X account",
    "isActive": true,
    "credentials": {
      "username": "<x-username>",
      "email": "<account-email>",
      "password": "<account-password>",
      "totp_secret": "<optional-base32-totp-secret>",
      "proxy_country": "US"
    }
  }'

The X connection is validated before it is stored. proxy_country must be a two-letter ISO country code. If the account uses TOTP, send the Base32 secret, not a temporary six-digit code.

Send account credentials only from a trusted backend. Do not embed them in browser JavaScript, mobile applications, logs, or source control.

List accounts

List every saved account:

curl \
  --url https://api.agenticscraper.com/api/v1/social-accounts \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY"

Filter by platform:

curl \
  --url "https://api.agenticscraper.com/api/v1/social-accounts?platform=x" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY"

Each item includes its UUID, platform, active state, validation state, safe metadata, and timestamps. Use the UUID in an automation’s accountIds.

Rename or disable an account

curl --request PATCH \
  --url "https://api.agenticscraper.com/api/v1/social-accounts/$ACCOUNT_ID" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY" \
  --data '{
    "name": "Research X account — paused",
    "isActive": false
  }'

At least one of name, isActive, or credentials is required.

Replace credentials

Credential updates are validated again. The account platform cannot be changed:

curl --request PATCH \
  --url "https://api.agenticscraper.com/api/v1/social-accounts/$ACCOUNT_ID" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY" \
  --data '{
    "credentials": {
      "redditClientId": "<new-client-id>",
      "redditClientSecret": "<new-client-secret>",
      "redditUserAgent": "my-product/2.0"
    }
  }'

Use the credential shape for the account’s existing platform.

Delete an account

curl --request DELETE \
  --url "https://api.agenticscraper.com/api/v1/social-accounts/$ACCOUNT_ID" \
  --header "X-API-Key: $AGENTIC_SCRAPER_API_KEY"

A successful deletion returns HTTP 204. For X accounts, the platform also attempts to disconnect the corresponding upstream account.

Select accounts in an automation

Select explicit accounts:

{
  "x": {
    "mode": "saved",
    "accountIds": [
      "11111111-1111-4111-8111-111111111111"
    ]
  }
}

Or select every saved account for the platform:

{
  "reddit": {
    "mode": "saved",
    "useAll": true
  }
}

The API rejects missing account IDs and rejects useAll when no saved account exists for that platform.