PATCH /v1/users/:userId/characters/:characterId

Use this endpoint to update an existing in-game character’s biographical data. All body fields are optional — you only need to include the fields you want to change. In addition to text fields, you can upload new avatar image files (avatar, signature, full-body PNG, and 3D GLB) as a multipart/form-data request. The endpoint also accepts 3D camera and bounding-box metadata via a JSON string in the avatar3D field.

Characters that have been approved cannot be edited. Attempting to update an approved character without ADMINISTRATOR or DEVELOPER permissions will return a 403 Forbidden error. If you need to make changes after submission, cancel the submission first to return the character to draft status.

This endpoint is rate-limited to 5 requests per minute. The request must be sent as multipart/form-data when uploading files. If you are only updating text fields, you may send a standard application/json body or nest the data inside a data JSON string field in the form.

Endpoint

PATCH https://api.cacolombia.com/v1/users/:userId/characters/:characterId

Path Parameters

string

required

The Snowflake ID of the user who owns the character. Must match the authenticated user’s ID.

string

required

The Snowflake ID of the character to update.

Query Parameters

string

Pass true to include the character’s signatureData field in the response after update. Omit or pass any other value to exclude it.

Request Body

All fields are optional. Send as multipart/form-data when uploading files, or as application/json for text-only updates.

string

Updated first name(s). Must be at least 2 characters long.

string

Updated last name(s). Must be at least 2 characters long.

number

Updated age in years.

number

Updated height in centimetres.

string

Updated gender. Must be exactly Masculino or Femenino.

string

Updated blood type. Must be one of: O+, O-, A+, A-, B+, B-, AB+, AB-.

string

Updated nationality name. Must be a valid nationality from the CA Colombia platform list.

string

Updated date of birth as an ISO 8601 date string (e.g. 1996-04-15).

file

A PNG image file to use as the character’s avatar. Upload as a form field named avatar.

file

A PNG image file to use as the character’s signature. Upload as a form field named signature.

file

A PNG image file for the character’s full-body reference. Upload as a form field named fullBody.

file

A GLB file for the character’s 3D avatar model. Upload as a form field named avatar3dGlb.

string

A JSON string containing 3D camera and bounding-box metadata. Must conform to the structure below.

Show avatar3D JSON structure

{
  "camera": {
    "position": { "x": 0.0, "y": 4.5, "z": 12.3 },
    "direction": { "x": 0.0, "y": -0.2, "z": -1.0 },
    "fov": 45.0
  },
  "aabb": {
    "min": { "x": -1.2, "y": 0.0, "z": -0.5 },
    "max": { "x": 1.2, "y": 5.8, "z": 0.5 }
  }
}

Response

Returns 200 OK with the full updated character object.

string

The character’s unique Snowflake ID.

string

The Snowflake ID of the user who owns this character.

string

The character’s first name(s).

string

The character’s last name(s).

number

The character’s age in years.

number

The character’s height in centimetres.

string

The character’s gender.

string

The character’s blood type.

object

An object describing the character’s nationality with nombre, abrev, and lugar fields.

string

The character’s date of birth in DD/MM/YYYY format.

string | null

Hash identifier for the character’s avatar image, updated if a new file was uploaded.

string | null

Hash identifier for the character’s generated ID card image.

string | null

Hash identifier for the character’s full-body image, updated if a new file was uploaded.

string | null

Hash identifier for the character’s 3D GLB model, updated if a new file was uploaded.

object | null

Camera metadata for the 3D avatar, updated if avatar3D was provided.

object | null

Bounding box metadata for the 3D avatar, updated if avatar3D was provided.

string

The character’s current ID card approval status.

object | null

The character’s in-game wallet, or null if none exists.

string

The character’s signature data. Only present when signature=true is passed.

string

ISO 8601 timestamp of when the character was created.

string

ISO 8601 timestamp of when the character was last updated.

Example Request (JSON — text fields only)

curl -X PATCH "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstNames": "Carlos Andrés",
    "age": 29
  }'

Example Request (multipart — with avatar upload)

curl -X PATCH "https://api.cacolombia.com/v1/users/112233445566778899/characters/998877665544332211" \
  -H "Authorization: Bearer <your_token>" \
  -F 'data={"firstNames":"Carlos Andrés","age":29}' \
  -F 'avatar=@/path/to/avatar.png'

Example Response

{
  "characterId": "998877665544332211",
  "userId": "112233445566778899",
  "firstNames": "Carlos Andrés",
  "lastNames": "Reyes Gómez",
  "age": 29,
  "height": 175,
  "gender": "Masculino",
  "bloodType": "O+",
  "nationality": {
    "nombre": "Colombiano",
    "abrev": "COL",
    "lugar": "Colombia"
  },
  "dob": "15/04/1996",
  "avatarHash": "newHash123abc",
  "idCardHash": null,
  "fullBodyHash": null,
  "avatar3dHash": null,
  "avatar3dCamera": null,
  "avatar3dAABB": null,
  "idStatus": "draft",
  "wallet": null,
  "createdAt": "2024-01-10T14:30:00.000Z",
  "updatedAt": "2024-06-15T11:45:00.000Z"
}

Error Responses

Status	Error	Description
`401`	`Unauthorized`	No valid authentication token was provided.
`403`	`Forbidden`	The authenticated user does not match the `userId` in the path.
`403`	`Forbidden`	The character has already been approved and cannot be edited without elevated permissions.
`400`	`Invalid form of body`	One or more fields failed validation. The response includes a `details` field describing each issue.
`404`	`Unknown User`	No user was found with the given `userId`.
`404`	`Unknown Character`	No character was found with the given `characterId` belonging to this user.

Overview

Auth & OAuth

Users

Characters

Economy

Banking

Staff

Utilities

PATCH /v1/users/:userId/characters/:characterId — Edit

Endpoint

Path Parameters

Query Parameters

Request Body

Response

Example Request (JSON — text fields only)

Example Request (multipart — with avatar upload)

Example Response

Error Responses

​Endpoint

​Path Parameters

​Query Parameters

​Request Body

​Response

​Example Request (JSON — text fields only)

​Example Request (multipart — with avatar upload)

​Example Response

​Error Responses

Endpoint

Path Parameters

Query Parameters

Request Body

Response

Example Request (JSON — text fields only)

Example Request (multipart — with avatar upload)

Example Response

Error Responses