A User is an isolated platform principal and account. The User API creates child Users managed by a parent User. Each child User has isolated resources, including bots, datasets, conversations, integrations, and settings. This isolation supports multi-tenant products built on top of the ChatBotKit platform.
Creating Users
To create a new child User, you need to send a POST request to the user creation endpoint. This operation can only be performed by the parent User. The created User will be linked to the caller as its parent User, inheriting billing and subscription settings while maintaining operational independence.
When creating a user, you can configure various properties including the user's display name, description, profile image, contact email, and resource limits. The contact email is particularly important as it allows you to associate customer contact information with the user for communication and support purposes.
POST /api/v1/user/create Content-Type: application/json Authorization: Bearer YOUR_API_TOKEN { "name": "Acme Corporation", "description": "Enterprise customer account", "email": "contact@acme.example.com" }http
The API returns the ID of the newly created user, which you'll use
for all subsequent operations related to this user. Store this ID
securely as it's required for managing the user's resources and
performing operations on their behalf using the X-RunAs-UserId header.
Important: Child Users share billing and subscription limits with their parent User. Ensure the parent User has sufficient capacity for all child Users and their resource usage. Resource limits can be customized per User to control individual usage caps.
Deleting Users
To permanently remove a user and all associated resources, send a POST request to the user delete endpoint. This operation is irreversible and will completely delete the user's account along with all their bots, datasets, conversations, integrations, files, and other resources.
Deleting a user should be done with extreme caution as it represents a complete account termination. All data belonging to the user will be permanently removed from the system, and there is no recovery mechanism. This operation is typically used when a customer cancels their subscription or when you need to clean up test or inactive accounts.
POST /api/v1/user/{userId}/delete Content-Type: application/json Authorization: Bearer YOUR_API_TOKEN {}http
Before deleting a user, consider whether you need to export or archive any of their data. Once deletion is complete, all conversation histories, trained models, uploaded files, and custom configurations are permanently removed and cannot be recovered.
Critical Warning: This operation cascades through all related resources. When a user is deleted, the system automatically removes all their bots, datasets, conversations, messages, integrations, API tokens, files, and any other resources they own. Ensure you have explicit confirmation from the customer before proceeding with account deletion.
Compliance: If you're subject to data retention regulations (such as GDPR, CCPA, or industry-specific requirements), ensure you have appropriate data export and archival processes in place before deleting user accounts. Some regulations require maintaining certain records even after account closure.
Best Practice: Implement a soft-delete or account suspension feature in your application layer before permanently deleting users. This provides a grace period where accounts can be restored if deletion was requested in error or if customers change their minds.
Fetching User Details
To retrieve detailed information about a specific user, send a GET request to the user fetch endpoint with the user's ID. This operation returns comprehensive information about the user, including all configuration settings, limits, and metadata.
Fetching individual user details is useful when you need to display account information, verify configuration settings, or prepare data for update operations. The endpoint provides a complete snapshot of the user's current state without including sensitive authentication credentials.
GET /api/v1/user/{userId}/fetch Authorization: Bearer YOUR_API_TOKENhttp
The response includes the user's ID, name, description, profile image, contact email, resource limits, custom metadata, and timestamp information. This data can be used to populate forms for editing, display account dashboards, or validate user configurations.
Use Case: When building a customer-account dashboard, use this endpoint to load detailed information when an operator selects a User from the list. This allows you to show comprehensive account details and provide edit functionality without loading all data upfront.
Updating Users
You can modify a user's properties by sending a POST request to the user update endpoint. This operation allows you to change the user's name, description, profile image, contact email, resource limits, and custom metadata without affecting their underlying resources or authentication credentials.
Updates to users are particularly useful when customer information changes, you need to adjust resource allocations, or you want to update branding elements like profile images. All properties except the user's ID and internal authentication details can be modified through this endpoint.
POST /api/v1/user/{userId}/update Content-Type: application/json Authorization: Bearer YOUR_API_TOKEN { "name": "Acme Corporation - Updated", "description": "Enterprise customer with expanded access", "email": "admin@acme.example.com" }http
The update operation is atomic and validates all input parameters before applying any changes. If validation fails, no modifications are made to the user account. The API returns the updated user's ID upon successful completion, confirming that changes have been applied.
Important: Updating resource limits affects what the user can create and access within their isolated account. Be cautious when reducing limits, as it may prevent the user from creating new resources until they're within the new constraints. Existing resources are not automatically deleted when limits are reduced.
Best Practice: When implementing an admin interface for managing users, fetch the current settings first, allow editing, then submit only the changed fields along with unchanged required fields to maintain consistency.
Listing Users
You can retrieve a list of all child users associated with your parent user by sending a GET request to the user list endpoint. This operation returns paginated results, allowing you to efficiently manage large numbers of customer accounts.
The list endpoint supports pagination through cursor-based navigation, enabling you to retrieve results in manageable chunks. You can control the order of results (ascending or descending by creation date) and specify how many items to retrieve per request using query parameters.
GET /api/v1/user/list?take=50&order=desc Authorization: Bearer YOUR_API_TOKENhttp
Each child User in the response includes basic information such as ID, name, profile image, contact email, configured limits, metadata, and timestamps for when the account was created and last updated. This information allows you to build comprehensive dashboards and management interfaces for your multi-user solution.
The response also includes pagination metadata when applicable, providing cursors for fetching the next page of results. This is particularly useful when building user interfaces that need to display large lists of customer accounts with smooth scrolling or pagination controls.
Best Practice: Implement caching strategies for user lists when building dashboards or management interfaces. Consider storing frequently accessed user data locally and refreshing it periodically or when updates occur, rather than fetching the entire list on every page load.
Note: The list endpoint only returns child Users that belong to the current parent User. You cannot access Users from other parent Users, ensuring complete isolation between account hierarchies.