> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.cacolombia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with CA Colombia API

> Make your first CA Colombia API call in four steps: connect OAuth, retrieve your user profile, create a character, and subscribe to WebSocket events.

This guide walks you through the four essential steps to get up and running with CA Colombia API. By the end, you'll have an authenticated session, a retrieved user profile, a newly created character, and an active WebSocket connection listening for live platform events.

<Steps>
  <Step title="Authenticate via OAuth">
    Before you can call any protected endpoint, you need an authenticated session. Start the OAuth flow by posting to `POST /v1/oauth/:provider` with your chosen provider (`discord` or `roblox`) and a `redirectUrl` that the API will send the player back to after they authorize.

    <Warning>
      You must complete Discord OAuth before you can link a Roblox account. Attempting the Roblox flow without an existing Discord-linked session will fail.
    </Warning>

    **Request**

    ```bash theme={null}
    curl -X POST https://api.cacolombia.com/v1/oauth/discord \
      -H "Content-Type: application/json" \
      -d '{"redirectUrl": "https://yourapp.com/auth/callback"}'
    ```

    **Response**

    ```json theme={null}
    {
      "targetUrl": "https://discord.com/oauth2/authorize?client_id=...&state=01J...",
      "state": "01J9XK2M4N7P3Q8R5T6W"
    }
    ```

    Redirect your user to `targetUrl`. After they authorize, the API will redirect them back to your `redirectUrl` with the `state` parameter appended as a query string. Session cookies (`access_token` and `refresh_token`) are set automatically on the callback — you do not need to handle tokens yourself.
  </Step>

  <Step title="Retrieve Your User Profile">
    Once authenticated, retrieve the current user's profile with `GET /v1/users/{userId}`. You must pass the user's own ID — you cannot view another user's profile unless you have elevated permissions.

    Append `?providers=true` to include linked OAuth provider details, or `?signature=true` to include character signature data.

    **Request**

    ```bash theme={null}
    curl https://api.cacolombia.com/v1/users/01J9XK2M4N7P3Q8R5T6W \
      --cookie "access_token=<your_session_cookie>"
    ```

    **Response**

    ```json theme={null}
    {
      "userId": "01J9XK2M4N7P3Q8R5T6W",
      "permissions": "1",
      "activeCharacter": null,
      "maxCharacters": 3,
      "characters": [],
      "createdAt": "2024-09-01T12:00:00.000Z",
      "updatedAt": "2024-09-01T12:00:00.000Z"
    }
    ```

    <Tip>
      Keep your `userId` handy — you'll need it for all subsequent requests scoped to your account, including character creation.
    </Tip>
  </Step>

  <Step title="Create a Character">
    Create your first roleplay character with `POST /v1/users/{userId}/characters`. The character starts in `draft` status and an ID card is generated automatically. You can submit it for staff review once it's ready.

    All fields in the request body are required. `gender` must be either `"Masculino"` or `"Femenino"`, and `bloodType` must be one of the eight supported values.

    **Request**

    ```bash theme={null}
    curl -X POST https://api.cacolombia.com/v1/users/01J9XK2M4N7P3Q8R5T6W/characters \
      -H "Content-Type: application/json" \
      --cookie "access_token=<your_session_cookie>" \
      -d '{
        "firstNames": "Carlos",
        "lastNames": "Rodríguez",
        "age": 28,
        "height": 175,
        "gender": "Masculino",
        "bloodType": "O+",
        "nationality": "Colombiano",
        "dob": "1996-04-15"
      }'
    ```

    **Response**

    ```json theme={null}
    {
      "userId": "01J9XK2M4N7P3Q8R5T6W",
      "characterId": "01J9XK8P2R4S6T7U9V0W",
      "firstNames": "Carlos",
      "lastNames": "Rodríguez",
      "age": 28,
      "height": 175,
      "gender": "Masculino",
      "bloodType": "O+",
      "nationality": {
        "nombre": "Colombiano",
        "abrev": "COL",
        "lugar": "Colombia"
      },
      "dob": "15/04/1996",
      "avatarHash": null,
      "idCardHash": null,
      "fullBodyHash": null,
      "avatar3dHash": null,
      "avatar3dCamera": null,
      "avatar3dAABB": null,
      "idStatus": "draft",
      "wallet": null,
      "createdAt": "2024-09-01T12:05:00.000Z",
      "updatedAt": "2024-09-01T12:05:00.000Z"
    }
    ```

    **Body schema reference**

    | Field         | Type   | Constraints                      |
    | ------------- | ------ | -------------------------------- |
    | `firstNames`  | string | Minimum 2 characters             |
    | `lastNames`   | string | Minimum 2 characters             |
    | `age`         | number | Integer                          |
    | `height`      | number | In centimetres                   |
    | `gender`      | string | `"Masculino"` or `"Femenino"`    |
    | `bloodType`   | string | `O+O-A+A-B+B-AB+AB-`             |
    | `nationality` | string | Must be a valid nationality name |
    | `dob`         | string | ISO 8601 date — `YYYY-MM-DD`     |
  </Step>

  <Step title="Connect to WebSocket">
    Connect to the CA Colombia WebSocket server to receive live platform events without polling. After establishing the connection, send a `subscribe` message to start receiving events for the topics you care about.

    **Connect**

    ```javascript theme={null}
    const socket = new WebSocket("wss://socket.cacolombia.com/");

    socket.addEventListener("open", () => {
      console.log("Connected to CA Colombia WebSocket");

      // Subscribe to character and economy events
      socket.send(JSON.stringify({
        type: "subscribe",
        topics: ["character.update", "wallet.update", "economy.transaction"]
      }));
    });
    ```

    **Incoming event example**

    ```json theme={null}
    {
      "type": "wallet.update",
      "characterId": "01J9XK8P2R4S6T7U9V0W",
      "data": {
        "balance": 4500,
        "updatedAt": "2024-09-01T12:10:00.000Z"
      }
    }
    ```

    **Handling messages**

    ```javascript theme={null}
    socket.addEventListener("message", (event) => {
      const payload = JSON.parse(event.data);

      switch (payload.type) {
        case "character.update":
          console.log("Character updated:", payload.characterId);
          break;
        case "wallet.update":
          console.log("New balance:", payload.data.balance);
          break;
        default:
          console.log("Event received:", payload);
      }
    });

    socket.addEventListener("close", (event) => {
      console.log("Connection closed:", event.code, event.reason);
    });
    ```

    <Tip>
      Implement reconnection logic with exponential backoff to handle transient network interruptions gracefully.
    </Tip>
  </Step>
</Steps>

## What's Next?

Now that you have a working session and your first character created, explore the full API surface:

* [**Authentication**](/authentication) — Understand cookie sessions, token refresh, and error codes in depth.
* **Character Endpoints** — Submit characters for review, update visuals, and manage ID status.
* **Economy & Banking** — Interact with wallets and bank accounts programmatically.
* **Staff Endpoints** — Approve or reject pending character submissions (requires elevated permissions).