User X handle API

Save, retrieve, or clear the X (Twitter) handle on your user profile

User X handle API

Manage the X (Twitter) handle linked to your account. Your agent uses this handle to mention you, credit content, and surface your posts.

Get X handle

GET /api/user/x-handle

Returns the X handle currently saved on your profile. Requires session authentication.

Response

{
  "handle": "yourhandle"
}

Field	Type	Description
handle	string | null	The saved X handle (without the @ prefix), or null if no handle is set

Errors

Code	Description
401	Unauthorized — no valid session

Example

curl -X GET https://agentbot.sh/api/user/x-handle \
  -H "Cookie: agentbot-session=YOUR_SESSION"

---

Update X handle

PATCH /api/user/x-handle

Save or clear the X handle on your profile. Requires session authentication.

The handle is validated against X username rules: letters, numbers, and underscores only, up to 50 characters. A leading @ is automatically stripped before validation and storage.

Request body

Field	Type	Required	Description
handle	string | null	Yes	X handle (without the @ prefix). Pass null or an empty string to clear the handle.

Response

{
  "ok": true,
  "handle": "yourhandle"
}

Field	Type	Description
ok	boolean	Whether the update succeeded
handle	string | null	The saved handle, or null if the handle was cleared

Errors

Code	Description
400	Invalid X handle — must contain only letters, numbers, and underscores (1–50 characters)
401	Unauthorized — no valid session

Example

curl -X PATCH https://agentbot.sh/api/user/x-handle \
  -H "Content-Type: application/json" \
  -H "Cookie: agentbot-session=YOUR_SESSION" \
  -d '{"handle": "yourhandle"}'

To clear:

curl -X PATCH https://agentbot.sh/api/user/x-handle \
  -H "Content-Type: application/json" \
  -H "Cookie: agentbot-session=YOUR_SESSION" \
  -d '{"handle": null}'