Try now →

Running Platform Actions

Drive LinkedIn, X, Reddit, and Instagram from the API with your API key - the same actions the MCP tools use.

One endpoint per action

Everything Wonda can do on a social platform is an endpoint:

POST /twin/sessions/{persona}/actions/{platform}/{action}

platform is linkedin, x, reddit, or instagram. action is a verb such as search, comment, or feed-engage. The full list, with payload fields for each, is in the Action Reference.

This is the same surface the Wonda MCP server uses. An MCP client and a plain HTTP client have the same capabilities - MCP is a thin wrapper over these endpoints, not a privileged path.

A read

curl -X POST \
  https://api.wondercat.ai/api/v1/twin/sessions/natty/actions/x/mentions \
  -H "Authorization: Bearer $WONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 20}'

The payload is a JSON object whose fields come from the action's row in the Action Reference. An action that takes no arguments still wants a body - send {}.

A write

curl -X POST \
  https://api.wondercat.ai/api/v1/twin/sessions/natty/actions/linkedin/comment \
  -H "Authorization: Bearer $WONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "target": "urn:li:activity:7123456789",
        "text": "The second point matches what we measured."
      }'

Writes consume a write slot. Reads do not. Slots are what the daily caps, cooldowns, and spend limits are counted against, so a read-heavy client is not rate-limited by write policy.

Some writes accept "dryRun": true, intended to run every check and report what would have happened without touching the platform. Support is per-action, and some actions accept the field without honouring it, so it is not a guaranteed safety net - see Dry runs.

Response shape

A successful call returns the action's result:

{
  "result": { "...": "action-specific" },
  "actionRunId": "run_01J...",
  "notices": [{ "code": "relay_update_available", "message": "..." }]
}

actionRunId identifies the run for audit. notices carries soft out-of-band hints riding a successful result; render each message and ignore codes you do not recognise rather than failing.

202: the session is warming

A control session that is not hot yet answers 202, not 200:

{ "status": "warming", "retryAfterMs": 2000 }

This is not an error and there is no error object. A client that treats any non-200 as failure will drop actions that would have succeeded, so branch on the status code before looking for error.

For a read, wait retryAfterMs and send the same request again.

For a write, do not retry blind. A 202 is also returned when the control session goes stale after the action was dispatched, and the spawned action is not cancelled, so the write may still complete. Confirm the current state before re-sending, exactly as with deferred - see Action Errors.

A failure returns a structured error rather than an HTTP-only signal:

{
  "error": {
    "message": "session needs re-authentication",
    "code": "needs_auth"
  }
}

The code is a stable, machine-readable value - branch on it, not on the message. See Action Errors for the full taxonomy and what to do about each one.

Discovering actions at runtime

The OpenAPI document describes every action endpoint with its typed request body:

curl https://api.wondercat.ai/api/v1/openapi.json

Each action is a distinct operation, so generated clients get real parameter types rather than an opaque blob.

Related