Copy page

WebSocket

Accounts over WebSocket

An account is a posting handle on TikTok, Instagram or YouTube, bound to a phone slot.

Accounts are linked, not signed in. The handle must already be signed in on the phone. These funs record it, move it between slots and remove it from the farm. There is no login, no logout and no account status anywhere in this API.

All five funs need the accounts ability. See Frames for the request and reply envelope.

Fun	Data fields	Reply
/app/accounts/list	page, platform	200 with {data, meta}
/app/accounts/get	account	200 with one account
/app/accounts/create	platform, handle, slot, notes, google_email	201 with the created account
/app/accounts/update	account, plus fields to change	200 with the updated account
/app/accounts/delete	account	204 with data: null

The account shape

Code
{
  "id": "6f2c8a41-95c1-4a2e-8f64-0b8d5e1c7a93",
  "platform": "tiktok",
  "handle": "@studio.nine",
  "slot": "b3f1c7e2-4a90-4d6f-9d1b-2c8e5f7a0d31",
  "notes": "morning shift",
  "created_at": "2026-01-20T11:02:41+00:00",
  "updated_at": "2026-02-11T08:55:10+00:00"
}

google_email appears on YouTube accounts only. An account id is a UUID that identifies its own platform, so /app/accounts/get, /app/accounts/update and /app/accounts/delete never ask which platform it is on.

What differs per platform

	TikTok	Instagram	YouTube
handle	Required	Required	Required
slot	Required, at most 4 accounts a phone	Optional	Optional
google_email	Rejected	Rejected	Required

platform defaults to tiktok when you leave it out. The cap of 4 accounts a phone counts TikTok accounts only, and is checked on TikTok creates and moves.

List accounts

Field	Type		Description
page	integer	optional	Page number, 1 or more. Defaults to 1.
platform	string	optional	Narrow to tiktok, instagram or youtube. Omit for every platform.

The reply is {"data": [...], "meta": {"current_page", "last_page", "per_page", "total"}}, 50 accounts a page, newest first. Every account carries its own platform.

Get an account

Field	Type		Description
account	string	required	Account UUID, on any platform.

The field is account, not account_id. An id you cannot see answers 404.

Create an account

Field	Type		Description
platform	string	optional	tiktok, instagram or youtube. Defaults to tiktok.
handle	string	required	Public @handle, up to 255 characters.
slot	string	see above	Phone slot UUID the account is bound to. Required on TikTok.
notes	string	optional	Free-form notes, up to 2000 characters.
google_email	string	see above	The Google account address of the channel. Required on YouTube, rejected elsewhere.

The reply is 201 with the created account.

Naming a slot means you must be able to control that phone, or the call is refused with 403 and You do not have permission to control the phone for this slot. That check runs before anything else, so a slot you cannot control never reports how full it is.

A fifth TikTok account on one phone is refused with 422 and This phone already holds the maximum of 4 accounts.

Omitting google_email on YouTube is refused with 422. Sending it on any other platform is refused too, with The google email field is prohibited.

Update an account

Field	Type		Description
account	string	required	Account UUID.
handle	string	optional	New @handle. Cannot be blanked.
slot	string	optional	Phone slot to move the account to.
notes	string	optional	New notes, or null to clear them.
google_email	string	optional	Editable on YouTube only.

Only the fields you send change. The platform cannot be changed here: the account lives on one platform for its whole life.

Moving an account onto a phone needs a control grant on the destination slot, the same as creating one. Owning the account is not enough.

Delete an account

Field	Type		Description
account	string	required	Account UUID.

The reply is 204 with data: null. This removes the account from the farm. It does not delete anything on TikTok, Instagram or YouTube.

Worked example: link, list, edit, remove