Update a conversation's access control | Kibana API documentation

Update a conversation's access control Technical Preview; added in 9.6.0

PUT /api/agent_builder/conversations/{conversation_id}/access_control

Spaces method and path for this operation:

put /s/{space_id}/api/agent_builder/conversations/{conversation_id}/access_control

Refer to Spaces for more information.

Replace a conversation's access mode and member list. Only the conversation owner can call this endpoint; every other caller receives a not-found response. Each call replaces the entire access control — the most recent successful update wins. Members can read and continue the conversation, but still need access to the conversation's agent. To learn more about agent conversations, refer to the agent chat documentation.

[Required authorization] Route required privileges: agentBuilder:read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

conversation_id string Required

The unique identifier of the conversation whose access control to update.

Maximum length is 256.

application/json

Body

access_mode string Required

Access-control mode: private (only the owner and the listed members can read and continue the conversation), public (any user with access to the conversation's agent can read and continue it).

Values are private or public.
entries array[object] Required

Members to share the conversation with. The list replaces the stored one; submit an empty list to unshare. Entries naming the owner are ignored. Must be empty when access_mode is public; repeated ids are rejected.

Not more than 100 elements.
Hide entries attributes Show entries attributes object
- id string Required
  
  Stable identifier of the user to share the conversation with: a Kibana user profile uid. Users without a profile cannot be granted access.
  
  Minimum length is 1, maximum length is 1024.
- role string Required
  
  Role granted to the principal. member is the only role: it grants read and converse access to the conversation.
  
  Value is member.
- type string Required
  
  Value is user.

Responses

200 application/json

Indicates a successful response
400 application/json

Bad Request — the request body failed validation.
404 application/json

Not Found — no conversation with this ID is readable by the caller, or the caller is not its owner. Matches the existing conversationNotFound shape, so members cannot distinguish a conversation they may not re-share from one that does not exist.

PUT /api/agent_builder/conversations/{conversation_id}/access_control

curl \
  -X PUT "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}/access_control" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "access_mode": "private",
    "entries": [
      { "type": "user", "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0", "role": "member" }
    ]
  }'

PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control
{
  "access_mode": "private",
  "entries": [
    { "type": "user", "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0", "role": "member" }
  ]
}

Request examples

Switch the conversation to `public` so any user with access to its agent can read and continue it. A public conversation is already open to everyone with agent access, so `entries` must be empty.

{
  "access_mode": "public",
  "entries": []
}

Example request sharing a private conversation with two users. They can read and continue the conversation, provided they also have access to its agent.

{
  "access_mode": "private",
  "entries": [
    {
      "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0",
      "role": "member",
      "type": "user"
    },
    {
      "id": "u_9xXGnqPB4mLTNhOlHMHXqYbGrGFOTuQIRWlqLpKq0dE_0",
      "role": "member",
      "type": "user"
    }
  ]
}

Submit an empty entries list to remove every member. Access then falls back to the access mode alone.

{
  "access_mode": "private",
  "entries": []
}

Response examples (200)

Example response returning the persisted access control. `added_at` is stamped by the server for newly added members and preserved for members that were already listed.

{
  "access_mode": "private",
  "entries": [
    {
      "added_at": "2026-08-11T10:00:00.000Z",
      "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0",
      "role": "member",
      "type": "user"
    },
    {
      "added_at": "2026-08-11T11:30:00.000Z",
      "id": "u_9xXGnqPB4mLTNhOlHMHXqYbGrGFOTuQIRWlqLpKq0dE_0",
      "role": "member",
      "type": "user"
    }
  ]
}

Response examples (400)

Two entries name the same user id.

{
  "error": "Bad Request",
  "message": "Duplicate ACL entry for user \"u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0\"",
  "statusCode": 400
}

`entries` must be empty when `access_mode` is `public` — a public conversation is already open to everyone with agent access.

{
  "error": "Bad Request",
  "message": "ACL entries are not supported when access_mode is \"public\"",
  "statusCode": 400
}

Request body exceeds the 100-member maximum.

{
  "error": "Bad Request",
  "message": "[request body.entries]: array size is [101], but cannot be greater than [100]",
  "statusCode": 400
}

Response examples (404)

{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Conversation my-conversation-id not found",
  "statusCode": 404
}