API reference

Calling the API

Use https://api.furipay.me/v1 as the base URL. The protected app API endpoints below require an access token; the token endpoint is the exception:

Authorization: Bearer YOUR_ACCESS_TOKEN

Rate limits

Limits are counted separately for each app and creator:

A limited request returns 429 with a Retry-After header.

Account and profile

GET /me identifies the creator represented by the token and needs no additional scope.

curl -X GET \
  'https://api.furipay.me/v1/me' \
  -H 'Authorization: Bearer <token>'

GET /profile returns the public profile, social links, and tip channels with their enabled state. It requires profile.read.

curl -X GET \
  'https://api.furipay.me/v1/profile' \
  -H 'Authorization: Bearer <token>'

Tips

GET /tips requires tips.read and accepts limit 1–100 (default 50), cursor, from, and to. Dates use ISO 8601.

curl -X GET \
  'https://api.furipay.me/v1/tips' \
  -H 'Authorization: Bearer <token>'

GET /tips/stats returns all-time and current-month tip totals and counts in THB.

curl -X GET \
  'https://api.furipay.me/v1/tips/stats' \
  -H 'Authorization: Bearer <token>'

POST /tips requires tips.create and accepts a positive amount within the platform cap, a 2–25 character name using A–Z, 0–9, underscores, or spaces, and an optional message up to 255 characters. Creator identity always comes from the token.

{
  "amount": 100,
  "name": "Nong",
  "message": "GG!"
}

This endpoint records a completed tip and emits its overlay event; it does not charge a supporter. Call it only after your source system has confirmed payment.

curl -X POST \
  'https://api.furipay.me/v1/tips' \
  -H 'Authorization: Bearer <token>'

Overlay and events

POST /alerts requires alerts.create and sends a test alert to the overlay without creating tip history.

curl -X POST \
  'https://api.furipay.me/v1/alerts' \
  -H 'Authorization: Bearer <token>'

GET /socket/token requires events.subscribe and returns a short-lived, ten-minute socket token.

curl -X GET \
  'https://api.furipay.me/v1/socket/token' \
  -H 'Authorization: Bearer <token>'

Error responses

Protected endpoints use one error envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires scope: tips.read"
  }
}

• 401 missing, invalid, or expired token
• 403 unusable grant or missing scope
• 422 request validation failed
• 429 rate limit exceeded
• 502 upstream service failed