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

Field	Type	Description
`id`	string	Unique buddy identifier
`userId`	string	ID of the owning user
`name`	string	Display name (max 30 characters)
`type`	string	Buddy type: `crab`, `robot`, `ghost`, `dragon`, or `alien`
`level`	integer	Current level (starts at 1)
`xp`	integer	Experience points accumulated
`energy`	integer	Energy level (0–100, starts at 50)
`happiness`	integer	Happiness level (0–100, starts at 50)
`lastFed`	string	ISO 8601 timestamp of last feed action
`lastPlayed`	string	ISO 8601 timestamp of last play action
`createdAt`	string	ISO 8601 timestamp when the buddy was created
`updatedAt`	string	ISO 8601 timestamp of last update

Errors

Code	Description
401	Unauthorized — 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

Field	Type	Required	Description
`name`	string	Yes	Display name for the buddy (max 30 characters)
`type`	string	Yes	Buddy 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

Code	Description
400	Invalid name (missing, non-string, or exceeds 30 characters)
400	Invalid buddy type (must be one of the valid types)
400	Maximum of 20 buddies reached
400	Invalid request body
401	Unauthorized — 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

Parameter	Type	Description
`buddyId`	string	The buddy’s unique identifier

Request body

Field	Type	Required	Description
`action`	string	Yes	Action to perform: `feed`, `play`, `train`, or `rename`
`newName`	string	Only for `rename`	New display name (1–30 characters)

Action effects

Action	Effect
`feed`	Energy +20 (capped at 100), happiness +10 (capped at 100), XP +10, updates `lastFed`
`play`	Happiness +15 (capped at 100), XP +25, updates `lastPlayed`
`train`	Energy −30 (requires at least 30), happiness −10 (floored at 0), XP +50
`rename`	Changes 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

Code	Description
400	Invalid action (must be `feed`, `play`, `train`, or `rename`)
400	Not enough energy to train (requires at least 30)
400	Invalid name for rename (must be a non-empty string, 1–30 characters)
400	Invalid request body
401	Unauthorized — no valid session
404	Buddy 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

Parameter	Type	Description
`buddyId`	string	The buddy’s unique identifier

Response

{
  "success": true
}

Errors

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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Buddies API

Buddies API

List buddies

Response

Buddy object fields

Errors

Hatch a buddy

Request body

Example request

Response (201)

Errors

Perform an action on a buddy

Path parameters

Request body

Action effects

Example requests

Response

Errors

Delete a buddy

Path parameters

Response

Errors

​Buddies API

​List buddies

​Response

​Buddy object fields

​Errors

​Hatch a buddy

​Request body

​Example request

​Response (201)

​Errors

​Perform an action on a buddy

​Path parameters

​Request body

​Action effects

​Example requests

​Response

​Errors

​Delete a buddy

​Path parameters

​Response

​Errors

Buddies API

List buddies

Response

Buddy object fields

Errors

Hatch a buddy

Request body

Example request

Response (201)

Errors

Perform an action on a buddy

Path parameters

Request body

Action effects

Example requests

Response

Errors

Delete a buddy

Path parameters

Response

Errors