# CA Colombia API

> Access the full CA Colombia ER:LC API documentation for services integrations.

## Docs

- [CA Colombia API: The Platform Backend for Roleplay](https://apidocs.cacolombia.com/introduction.md): CA Colombia API provides authentication, character management, in-game economy, banking, and real-time events for the CA Colombia Roblox roleplay platform.
- [Get Started with CA Colombia API](https://apidocs.cacolombia.com/quickstart.md): Make your first CA Colombia API call in four steps: connect OAuth, retrieve your user profile, create a character, and subscribe to WebSocket events.
- [Authenticate with CA Colombia API](https://apidocs.cacolombia.com/authentication.md): CA Colombia API uses cookie-based sessions issued after OAuth with Discord or Roblox. Learn to initiate OAuth, handle callbacks, and manage session expiry.
- [Users and Identity Providers in CA Colombia](https://apidocs.cacolombia.com/concepts/users-and-providers.md): A CA Colombia user account links a Discord identity and a Roblox account. Learn how providers work, what data is stored, and how accounts are created.
- [Characters: In-Game Personas in CA Colombia](https://apidocs.cacolombia.com/concepts/characters.md): Characters are in-game personas with biographic data, a generated ID card, and a lifecycle from draft to approved. Learn about character fields and statuses.
- [In-Game Economy and Wallets in CA Colombia](https://apidocs.cacolombia.com/concepts/economy.md): Each approved character has a wallet tracking their balance. Learn how the economy works, wallet fields, and how to read and update balances.
- [Permission Roles and Access Control in CA Colombia](https://apidocs.cacolombia.com/concepts/permissions.md): CA Colombia API uses bitfield-based permission roles. Learn what each role grants, which endpoints require elevated permissions, and how access is enforced.
- [Complete the OAuth Flow with Discord and Roblox](https://apidocs.cacolombia.com/guides/oauth-flow.md): Connect a Discord and Roblox account to CA Colombia using OAuth 2.0. Follow these steps to initiate the flow, handle the callback, and establish a session.
- [Managing Character Lifecycle in CA Colombia](https://apidocs.cacolombia.com/guides/character-lifecycle.md): Create, submit, and manage the approval lifecycle of in-game characters. Walk through every state transition from draft creation to active approved character.
- [Set Up and Manage In-Game Banks](https://apidocs.cacolombia.com/guides/banking.md): Create banks with character owners, manage bank accounts, check balances, and link accounts to characters. A complete guide to the CA Colombia banking system.
- [Subscribe to Real-Time Events via WebSocket](https://apidocs.cacolombia.com/guides/websocket.md): Connect to CA Colombia's WebSocket server to receive real-time events for users and characters. Learn how to subscribe to topics and handle incoming messages.
- [Error Responses and Status Codes Reference](https://apidocs.cacolombia.com/reference/errors.md): CA Colombia API returns structured JSON errors. Understand HTTP status codes, error codes, and how to handle authentication and validation failures.
- [Rate Limits and Request Throttling](https://apidocs.cacolombia.com/reference/rate-limits.md): CA Colombia API enforces per-window rate limits on endpoints. Learn the default limits, how to read rate limit errors, and which roles bypass throttling.
- [Real-Time Events via WebSocket Subscriptions](https://apidocs.cacolombia.com/reference/webhooks.md): CA Colombia broadcasts real-time events over WebSocket topics. Learn the event payload structure for user and character events.
- [CA Colombia REST API — Complete Reference Overview](https://apidocs.cacolombia.com/api-reference/overview.md): Full reference for the CA Colombia REST API. Base URL, authentication, request format, versioning, and links to every endpoint group.
- [Initiate OAuth 2.0 Flow — POST /v1/oauth/:provider](https://apidocs.cacolombia.com/api-reference/oauth/initiate.md): Start an OAuth 2.0 authorization flow with Discord or Roblox. Returns the provider authorization URL and a state token for the callback.
- [OAuth 2.0 Provider Callback — GET /v1/oauth/:provider](https://apidocs.cacolombia.com/api-reference/oauth/callback.md): The OAuth 2.0 provider callback endpoint. Validates the state token, exchanges the authorization code for a session, and sets access and refresh cookies.
- [Get User Profile — GET /v1/users/:userId — CA Colombia](https://apidocs.cacolombia.com/api-reference/users/get-user.md): Fetch a CA Colombia user by their Snowflake ID. Returns profile data, character list, and optionally linked Discord and Roblox provider accounts.
- [Get Full-Body Roblox Avatar — GET /roblox/avatar](https://apidocs.cacolombia.com/api-reference/users/get-avatar.md): Retrieve a user's full-body Roblox avatar image through the CA Colombia API. Returns a JSON image URL or raw PNG binary when download=true.
- [Get Roblox Avatar Bust — GET /roblox/avatar-bust](https://apidocs.cacolombia.com/api-reference/users/get-avatar-bust.md): Retrieve a user's Roblox avatar bust (upper body) image at 420×420 PNG resolution. Returns a JSON image URL or raw PNG binary when download=true.
- [Get Roblox 3D Avatar Data — GET /roblox/avatar-3d](https://apidocs.cacolombia.com/api-reference/users/get-avatar-3d.md): Retrieve a user's Roblox 3D avatar model data, including OBJ, MTL, and texture file references plus camera and bounding-box metadata.
- [GET /v1/users/:userId/characters — List Characters](https://apidocs.cacolombia.com/api-reference/characters/list-characters.md): List all in-game characters belonging to a CA Colombia user. Returns an array of character objects with status and biographical data.
- [POST /v1/users/:userId/characters — Create Character](https://apidocs.cacolombia.com/api-reference/characters/create-character.md): Create a new in-game character for a CA Colombia user. All biographical fields required. Character starts in draft status, ready for avatar and signature uploads.
- [GET /v1/users/:userId/characters/:characterId — Get](https://apidocs.cacolombia.com/api-reference/characters/get-character.md): Fetch a single in-game character by ID. Returns all biographical fields, visual asset hashes, idStatus, and wallet data for the character.
- [PATCH /v1/users/:userId/characters/:characterId — Edit](https://apidocs.cacolombia.com/api-reference/characters/update-character.md): Partially update a character's biographical fields and avatar assets. All fields optional. Editing approved characters requires ADMINISTRATOR or DEVELOPER permission.
- [POST /v1/users/:userId/characters/:characterId/submit](https://apidocs.cacolombia.com/api-reference/characters/submit-character.md): Submit a draft character for staff review. Transitions the character from draft to pending_approval, locking further edits until reviewed or cancelled.
- [POST /v1/users/:userId/characters/:characterId/cancel](https://apidocs.cacolombia.com/api-reference/characters/cancel-character.md): Cancel a pending_approval character submission and return it to draft status. Allows the owner to make edits before resubmitting for staff review.
- [GET /v1/users/:userId/characters/:characterId/wallet](https://apidocs.cacolombia.com/api-reference/economy/get-wallet.md): Retrieve the in-game wallet for an approved character. Returns the character's current cash balance, wallet ID, and creation timestamps.
- [PATCH/PUT /v1/users/:userId/characters/:characterId/wallet](https://apidocs.cacolombia.com/api-reference/economy/update-wallet.md): Update a character's in-game wallet. PATCH sets an exact absolute balance; PUT applies a signed transaction delta to the current balance. Both require ADMINISTRATOR.
- [POST /v1/banks — Create and Register an In-Game Bank](https://apidocs.cacolombia.com/api-reference/banks/create-bank.md): Register a new in-game bank owned by an existing character. Requires SERVICE_ADMINISTRATOR permission. Optionally sets the bank's starting capital balance.
- [GET /v1/banks/:bankId — Retrieve Bank Information](https://apidocs.cacolombia.com/api-reference/banks/get-bank.md): Retrieve details about a specific in-game bank by its ID, including display name, current capital, icon hash, and owner character ID.
- [PATCH/PUT /v1/banks/:bankId — Update Bank Record](https://apidocs.cacolombia.com/api-reference/banks/update-bank.md): Update a bank's name, owner, or icon via PATCH, or apply a capital transaction via PUT. Updating capital or using PUT requires the ADMINISTRATOR permission.
- [DELETE /v1/banks/:bankId — Permanently Delete Bank](https://apidocs.cacolombia.com/api-reference/banks/delete-bank.md): Permanently remove an in-game bank from the platform. Requires ADMINISTRATOR permission. Returns the bank object as it existed immediately before deletion.
- [GET /v1/banks/:bankId/accounts — List Bank Accounts](https://apidocs.cacolombia.com/api-reference/banks/list-accounts.md): List all accounts belonging to an in-game bank. Restricted to the bank owner and users with STAFF permission. Returns an array of account objects.
- [GET /v1/banks/:bankId/accounts/:accountId — Details](https://apidocs.cacolombia.com/api-reference/banks/get-account.md): Retrieve a single bank account by ID. Returns balance and linked character ID. Requires that one of your characters owns the account, or STAFF permission.
- [POST /v1/banks/:bankId/accounts — Create Bank Account](https://apidocs.cacolombia.com/api-reference/banks/create-account.md): Open a new bank account for a character within a specific bank. Each character may hold only one account per bank. New accounts start with a zero balance.
- [GET /v1/banks/:bankId/accounts/:accountId — Balance](https://apidocs.cacolombia.com/api-reference/banks/get-balance.md): Retrieve only the current balance of a bank account without fetching the full account object. Requires account ownership or STAFF permission to access.
- [GET /v1/staff/characters/pending — List Pending Characters](https://apidocs.cacolombia.com/api-reference/staff/pending-characters.md): Retrieve a paginated list of characters in pending_approval status awaiting staff review. Requires MODERATOR_CHIEF, ADMINISTRATOR, or DEVELOPER permission.
- [POST /v1/staff/characters/approve — Approve Characters](https://apidocs.cacolombia.com/api-reference/staff/approve-character.md): Approve one or more submitted characters in a single batch request. Requires MODERATOR_CHIEF, ADMINISTRATOR, or DEVELOPER permission.
- [POST /v1/staff/characters/reject — Reject Characters](https://apidocs.cacolombia.com/api-reference/staff/reject-character.md): Reject one or more pending_approval characters, resetting their idStatus to draft. Requires MODERATOR_CHIEF, ADMINISTRATOR, or DEVELOPER permission.
- [GET /v1/health — CA Colombia API Health Endpoint](https://apidocs.cacolombia.com/api-reference/health.md): Verify that the CA Colombia API is online and accepting requests. No authentication required. Returns HTTP 200 with no body when the service is healthy.
- [GET /v1/images/:type/:hash — Retrieve Stored Image](https://apidocs.cacolombia.com/api-reference/images.md): Stream a stored image or 3D model file by type and hash identifier. Supports avatar, id card, full-body, 3D GLB model, and bank icon asset types.