Instances

Instances are the WhatsApp connections under your account. The full lifecycle lives in Concepts → Instances; this page covers the wire shape.

List instances

GET/v1/instancesBearer · API key

Returns every instance owned by the authenticated customer, newest first. Soft-deleted instances are excluded.

curl -s "$WHATISUP_API/v1/instances" \
  -H "Authorization: Bearer $WHATISUP_API_KEY"

{
  "data": [
    {
      "id": "inst_01J7...",
      "customer_id": "cust_01J6...",
      "name": "primary",
      "phone_number": "5511999999999",
      "status": "connected",
      "last_seen_at": "2026-05-01T12:34:56.000Z",
      "metadata": {},
      "created_at": "2026-04-12T08:11:32.000Z",
      "updated_at": "2026-05-01T12:34:56.000Z"
    }
  ]
}

Create instance

POST/v1/instancesBearer · API key

Schema · Request body

Field	Type	Required	Notes
name	string	required
metadata	object	optional

curl -sX POST "$WHATISUP_API/v1/instances" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"support-line","metadata":{"team":"support"}}'

The response is an Instance object. Status starts at pending — the Baileys session is not yet allocated. Fetch the QR to start one.

Schema · Response · Instance

Field	Type	Required
id	string · uuid	required
customer_id	string · uuid	required
name	string	required
phone_number	string	required · nullable
status	`pending` \\| `qr` \\| `connecting` \\| `connected` \\| `disconnected` \\| `failed`	required
last_seen_at	string · ISO 8601	required · nullable
metadata	object	required
created_at	string · ISO 8601	required
updated_at	string · ISO 8601	required

Get one instance

GET/v1/instances/:idBearer · API key

Returns the single instance. 404s for instances that belong to a different customer (we never leak a "wrong tenant" 403; both look like "not found").

Get the current QR

GET/v1/instances/:id/qrBearer · API key

Lazily starts the Baileys session if one isn't running, then waits up to ~10s for a QR. Returns data:image/png;base64,… plus the raw wire-format string (handy if you want to render with your own QR library) and an expires_at.

{
  "qr": "data:image/png;base64,iVBORw0KGgo...",
  "raw": "2@dPBI4Tg9Mc...,vlD4Pmkr...",
  "expires_at": "2026-05-01T12:35:25.000Z"
}

The dashboard's Pair flow uses SSE instead — it gets the QR pushed without polling.

Soft-delete

DELETE/v1/instances/:idBearer · API key

Stops the socket, wipes auth-state, marks the row deleted. Webhook deliveries that referenced this instance stay queryable for forensics.

curl -sX DELETE "$WHATISUP_API/v1/instances/inst_01J..." \
  -H "Authorization: Bearer $WHATISUP_API_KEY"

Returns 204 No Content.