Skip to main content

​
Buddies API

Create and interact with virtual buddies. Each authenticated user can own up to 20 buddies. All endpoints require session authentication.

​
List buddies

GET /api/buddies
Returns all buddies owned by the authenticated user, ordered by creation date (oldest first).

​
Response

{
  "buddies": [
    {
      "id": "clx1abc2d0001ab12example",
      "userId": "user_abc",
      "name": "Sparky",
      "type": "dragon",
      "level": 1,
      "xp": 0,
      "energy": 50,
      "happiness": 50,
      "lastFed": "2026-04-09T04:00:00.000Z",
      "lastPlayed": "2026-04-09T04:00:00.000Z",
      "createdAt": "2026-04-09T04:00:00.000Z",
      "updatedAt": "2026-04-09T04:00:00.000Z"
    }
  ]
}

​
Buddy object fields

FieldTypeDescription
idstringUnique buddy identifier
userIdstringID of the owning user
namestringDisplay name (max 30 characters)
typestringBuddy type: crab, robot, ghost, dragon, or alien
levelintegerCurrent level (starts at 1)
xpintegerExperience points accumulated
energyintegerEnergy level (0–100, starts at 50)
happinessintegerHappiness level (0–100, starts at 50)
lastFedstringISO 8601 timestamp of last feed action
lastPlayedstringISO 8601 timestamp of last play action
createdAtstringISO 8601 timestamp when the buddy was created
updatedAtstringISO 8601 timestamp of last update

​
Errors

CodeDescription
401Unauthorized — no valid session

​
Hatch a buddy

POST /api/buddies
Creates a new buddy for the authenticated user. New buddies start with 50 energy and 50 happiness.

​
Request body

FieldTypeRequiredDescription
namestringYesDisplay name for the buddy (max 30 characters)
typestringYesBuddy type: crab, robot, ghost, dragon, or alien

​
Example request

{
  "name": "Sparky",
  "type": "dragon"
}

​
Response (201)

{
  "buddy": {
    "id": "clx1abc2d0001ab12example",
    "userId": "user_abc",
    "name": "Sparky",
    "type": "dragon",
    "level": 1,
    "xp": 0,
    "energy": 50,
    "happiness": 50,
    "lastFed": "2026-04-09T04:00:00.000Z",
    "lastPlayed": "2026-04-09T04:00:00.000Z",
    "createdAt": "2026-04-09T04:00:00.000Z",
    "updatedAt": "2026-04-09T04:00:00.000Z"
  }
}

​
Errors

CodeDescription
400Invalid name (missing, non-string, or exceeds 30 characters)
400Invalid buddy type (must be one of the valid types)
400Maximum of 20 buddies reached
400Invalid request body
401Unauthorized — no valid session

​
Perform an action on a buddy

PATCH /api/buddies/{buddyId}
Perform an action on a buddy. The buddy must belong to the authenticated user. Available actions are feed, play, train, and rename.

​
Path parameters

ParameterTypeDescription
buddyIdstringThe buddy’s unique identifier

​
Request body

FieldTypeRequiredDescription
actionstringYesAction to perform: feed, play, train, or rename
newNamestringOnly for renameNew display name (1–30 characters)

​
Action effects

ActionEffect
feedEnergy +20 (capped at 100), happiness +10 (capped at 100), XP +10, updates lastFed
playHappiness +15 (capped at 100), XP +25, updates lastPlayed
trainEnergy −30 (requires at least 30), happiness −10 (floored at 0), XP +50
renameChanges the buddy’s display name (requires newName in the request body)

​
Example requests

Feed a buddy: 
{
  "action": "feed"
}
Train a buddy: 
{
  "action": "train"
}
Rename a buddy: 
{
  "action": "rename",
  "newName": "Blaze"
}

​
Response

For feed, play, and train actions the response includes a leveledUp boolean indicating whether the buddy gained a level from the action: 
{
  "buddy": {
    "id": "clx1abc2d0001ab12example",
    "userId": "user_abc",
    "name": "Sparky",
    "type": "dragon",
    "level": 2,
    "xp": 110,
    "energy": 70,
    "happiness": 60,
    "lastFed": "2026-04-09T05:00:00.000Z",
    "lastPlayed": "2026-04-09T04:00:00.000Z",
    "createdAt": "2026-04-09T04:00:00.000Z",
    "updatedAt": "2026-04-09T05:00:00.000Z"
  },
  "leveledUp": true
}
For the rename action, only the updated buddy object is returned (no leveledUp field): 
{
  "buddy": {
    "id": "clx1abc2d0001ab12example",
    "userId": "user_abc",
    "name": "Blaze",
    "type": "dragon",
    "level": 2,
    "xp": 110,
    "energy": 70,
    "happiness": 60,
    "lastFed": "2026-04-09T05:00:00.000Z",
    "lastPlayed": "2026-04-09T04:00:00.000Z",
    "createdAt": "2026-04-09T04:00:00.000Z",
    "updatedAt": "2026-04-09T05:30:00.000Z"
  }
}

​
Errors

CodeDescription
400Invalid action (must be feed, play, train, or rename)
400Not enough energy to train (requires at least 30)
400Invalid name for rename (must be a non-empty string, 1–30 characters)
400Invalid request body
401Unauthorized — no valid session
404Buddy not found or does not belong to the authenticated user

​
Delete a buddy

DELETE /api/buddies/{buddyId}
Permanently deletes a buddy. The buddy must belong to the authenticated user.

​
Path parameters

ParameterTypeDescription
buddyIdstringThe buddy’s unique identifier

​
Response

{
  "success": true
}

​
Errors

CodeDescription
401Unauthorized — no valid session
404Buddy not found or does not belong to the authenticated user