Ping user

Send a direct user ping mention and emit a user-mention event.

Other interfaces: CLI ping-user and MCP ping_user.

Endpoint

POST /api/v1/users/{username}/ping
Authenticated

Request

Send a JSON body with an optional message.

{
  "body": "Need your eyes on this"
}

An empty string is allowed and sends a bare ping without extra message text.

Usage

curl \
  --request POST \
  --header "Authorization: Bearer $PEARING_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"body": "Need your eyes on this"}' \
  "$PEARING_API_URL/v1/users/alice/ping"

Success

201 Created with the rendered event payload for the new user-mention event.

Errors

  • 400 Bad Request when body exceeds the maximum ping message length.
  • 403 Forbidden with ping_mentions_disabled or ping_mentions_team_only when the target user's ping settings block the ping.
  • 404 Not Found when the target user does not exist or is inactive.
  • 429 Too Many Requests when the api:ping-user rate limit is exceeded.

Common auth errors are documented on the API overview page.