Try now →

Personas and Sessions

How Wonda models a social account you control, and how to address one from the API.

What a persona is

A persona is one social account Wonda can act as - a LinkedIn profile, an X handle, a Reddit user, an Instagram account. Every action you run through the API names the persona it should run as.

Personas are addressed by a short slug you choose when connecting the account:

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

A persona holds the logged-in session for that account. You never send platform credentials to the API - you sign in once through Wonda, and the session lives either on your own machine or on the account's hosted browser. See Routing for which one runs a given call.

Listing your personas

curl https://api.wondercat.ai/api/v1/twin/sessions \
  -H "Authorization: Bearer $WONDA_API_KEY"

The response lists each persona with the platform it belongs to and whether its session is currently usable.

Session health

A persona's session can lapse - a platform signs you out, requires a re-verification, or flags the account. Actions against a lapsed session fail with needs_auth rather than silently doing nothing.

To check health without running an action, read it:

curl https://api.wondercat.ai/api/v1/twin/sessions/natty/health \
  -H "Authorization: Bearer $WONDA_API_KEY"

That returns the twin's lifecycle status and its ban-signal health.

Do not use POST /twin/needs-auth as a probe. Despite the name it is a write: it flags the twin as needing re-authentication and pauses its schedules. Call it when you have established a session is dead, never to ask whether it is.

Re-authenticating is deliberately a human step: it happens in a visible browser where the person signs in themselves, including any 2FA. There is no API for submitting a platform password, and there will not be one. See Controlling the Browser for opening that window.

Access and roles

An API key acts for the account that owns it. Personas belonging to an organization are reachable when your key's account has an operator role on that persona. Without one - including a read-only grant, or a persona that does not exist - the call fails with 403 and code forbidden.

Related