PocketPass API

// Send the user here
https://dev.pocketpass.xyz/authorize
  ?client_id=YOUR_CLIENT_ID
  &scopes=read:profile,read:encounters
  &redirect_uri=https://yourapp.com/callback

https://yourapp.com/callback?code=AUTH_CODE

POST https://pocketpass.xyz/functions/v1/api-token

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "code": "AUTH_CODE"
}

{
  "access_token": "abc-123-...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scopes": ["read:profile", "read:encounters"]
}

// 1. Generate code_verifier (random 43-128 char string)
// 2. Compute code_challenge = base64url(SHA-256(code_verifier))
// 3. Add code_challenge to authorize URL
?client_id=...&scopes=...&code_challenge=HASH

// 4. Include code_verifier in token exchange
{ "code_verifier": "ORIGINAL", ... }

GET /me
Authorization: Bearer YOUR_ACCESS_TOKEN

Returns the authorized user's profile.

{
  "id": "312c8f81-ae71-...",
  "user_name": "simply0004",
  "avatar_hex": "AwEA...",
  "greeting": "Hello!",
  "mood": "HAPPY",
  "origin": "Sweden",
  "age": "18",
  "hobbies": "Gaming",
  "is_male": true,
  "friend_code": "56814231",
  "selected_games": ["Animal Crossing", "Mario Kart"],
  "token_balance": 42,
  "puzzle_progress": { ... }
}

Update the user's greeting or mood. Only the fields you send are updated.

{
  "greeting": "Hey there!",
  "mood": "EXCITED"
}

Valid moods: HAPPY, SAD, EXCITED, SLEEPY, ANGRY, COOL, SHY, CONFUSED

Returns the user's Piip as a PNG image.

Param	Default	Description
width	270	Image width: 128, 256, or 512
type	face	face, face_body, or all_body

Response: image/png binary data.

// Embed in HTML
<img src="https://pocketpass.xyz/functions/v1/api-v1/me/avatar?width=256" />

// Fetch with token
fetch('/me/avatar?width=128', {
  headers: { 'Authorization': 'Bearer TOKEN' }
})

Returns any user's Piip avatar by their user ID. Same query params as /me/avatar.

Returns the user's encounter history, sorted newest first.

Param	Default	Description
limit	50	Max 100
offset	0	Pagination offset

[
  {
    "other_user_id": "uuid",
    "other_user_name": "Nashi",
    "other_user_avatar_hex": "AwEA...",
    "origin": "Japan",
    "greeting": "Hello!",
    "meet_count": 3,
    "timestamp": 1711152000000
  }
]

Returns the user's accepted friends with basic profile info.

[
  {
    "id": "uuid",
    "user_name": "Bubbleeey",
    "avatar_hex": "AwEA...",
    "origin": "UK",
    "greeting": "Hi!",
    "mood": "HAPPY",
    "friend_code": "08375706"
  }
]

Returns global leaderboard rankings.

Param	Default	Description
sort	total_encounters	Sort field (see below)
limit	50	Max 100

Sort options: total_encounters, unique_encounters, unique_regions, puzzles_completed, achievements_unlocked

[
  {
    "user_id": "uuid",
    "user_name": "xevylicious",
    "avatar_hex": "AwEA...",
    "total_encounters": 247,
    "unique_encounters": 189,
    "unique_regions": 14,
    "puzzles_completed": 8,
    "achievements_unlocked": 12
  }
]

Returns all published SpotPass items (puzzle panels and events).

[
  {
    "id": "uuid",
    "type": "puzzle_panel",
    "title": "Castle Collection",
    "description": "A medieval castle puzzle",
    "panel_image_url": "https://...",
    "published_at": "2026-03-20T12:00:00Z",
    "expires_at": null
  },
  {
    "id": "uuid",
    "type": "event",
    "title": "Double Token Weekend",
    "event_effect": "{\"type\":\"token_multiplier\",\"value\":2}",
    "published_at": "2026-03-25T00:00:00Z",
    "expires_at": "2026-03-27T00:00:00Z"
  }
]

Send a message to a friend. The receiver must be in the user's friend list.

{
  "receiver_id": "friend-uuid",
  "content": "Hello from the API!"
}

Returns 201 Created on success.

{
  "error": "Token does not have the required scope: read:friends"
}