Partner User Contexts

Partner user contexts let you bind a partner user (sub-account) to a set of platform resources - a blueprint, bot, dataset, or skillset - along with a free-form payload object. This is useful when each of your customers should operate within a pre-defined AI configuration, or when you want to attach arbitrary metadata to a customer's resource scope without modifying the underlying resource.

Contexts are managed entirely by the parent partner account on behalf of its sub-accounts, using the same X-RunAs-UserId header pattern that applies to all partner operations. The sub-account's isolated environment remains unchanged; the context is an additional layer of linkage.

Creating a Partner User Context

Send a POST request with the target partner user's ID in the path and the desired resource associations in the request body. All resource references (blueprintId, botId, datasetId, skillsetId) are optional, so you can link as many or as few as the use case requires.

The optional payload field accepts any JSON object, making it a flexible store for configuration data, user preferences, or integration-specific settings that your application needs to attach to the context.

The response contains the full context record including all linked resource IDs, the payload, and standard metadata fields (id, createdAt, updatedAt).

Note: At least one resource ID or a payload value should be provided, though the API does not enforce this constraint. Contexts with no resource links and no payload offer no practical value.

Listing Partner User Contexts

Retrieve a paginated list of all contexts that belong to a specific partner user. Results are returned in reverse chronological order by default and support cursor-based pagination for large result sets.

You can narrow results by providing one or more resource filter parameters as query strings. For example, passing botId=bot_abc123 will return only contexts that reference that particular bot. Multiple filters can be combined to find contexts linked to a specific combination of resources.

The response includes an items array of context objects and a cursor value for fetching the next page. When cursor is an empty string, you have reached the last page. Pass the returned cursor as the cursor query parameter in the next request to continue pagination.

Available filter parameters:

• blueprintId - Filter contexts linked to a specific blueprint
• botId - Filter contexts linked to a specific bot
• datasetId - Filter contexts linked to a specific dataset
• skillsetId - Filter contexts linked to a specific skillset
• meta - Filter by metadata key-value pairs using deep object notation

Tip: Use the order=asc parameter when you need to process contexts in creation order, for example when synchronising context data with an external system.

Fetching a Single Partner User Context

Retrieve a single context by its ID within a partner user's account. This endpoint is useful when you need the full details of a specific context, including its linked resource IDs and the custom payload object, without loading the entire list.

The response returns the full context record including id, name, description, blueprintId, botId, datasetId, skillsetId, payload, meta, createdAt, and updatedAt. Resource ID fields that were not set during creation will be null.

Authorization: The context must belong to the partner user identified by the userId path parameter. Attempting to fetch a context that belongs to a different user will return a 401 Not Authorized error.

Updating a Partner User Context

Modify an existing partner user context. All fields are optional in the update request; only the fields you include will be changed. This follows the standard ChatBotKit partial-update pattern.

Common update scenarios include changing the linked bot when a customer upgrades to a different configuration, updating the payload to reflect changed preferences, or reassigning a context to a different blueprint.

The response contains only the context id to confirm which record was updated. Retrieve the full updated record using the fetch endpoint if you need to verify the new field values.

Note: Passing null for a resource ID field (e.g. "botId": null) will clear the link for that resource. Omitting the field entirely leaves the existing value unchanged.

Deleting a Partner User Context

Permanently remove a partner user context. This operation cannot be undone. The associated platform resources (bot, dataset, etc.) are not affected - only the context record itself is removed.

Deleting a context is appropriate when a customer is being offboarded, when a resource configuration is being replaced by a new context, or when a context was created in error.

The response confirms the deletion by returning the id of the removed context. Any attempt to fetch, update, or delete the same context ID after deletion will return a 404 Not Found error.

Warning: Deleting a context does not cascade to the linked resources. If your application logic depends on a context to route requests to the correct bot or dataset, ensure you update that logic before removing the context to avoid broken integrations.