Update a conversation's access control

Base URL: https://{kibana_url}

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

Auth

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

Privileges agentBuilder:read

Path parameters

space_id string optional: An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
conversation_id string · max length: 256 required: The unique identifier of the conversation whose access control to update.

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

access_mode enum 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: private public
entries object[] · max items: 100 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.

Responses

200

Indicates a successful response

application/json

400

Bad Request — the request body failed validation.

application/json

404

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.

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

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" }
    ]
  }'

Response

No example

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

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

Request Console 1 / 2 languages

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.

Console Kibana Dev Tools

PUT kbn:/api/agent_builder/conversations/CONVERSATION_ID/access_control
{
  "access_mode": "public",
  "entries": []
}

Generated from the API spec

curl Shell

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": "public",
    "entries": []
  }'

Generated from the API spec

Response

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"
    }
  ]
}

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

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

curl Shell

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": [
      {
        "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0",
        "role": "member",
        "type": "user"
      },
      {
        "id": "u_9xXGnqPB4mLTNhOlHMHXqYbGrGFOTuQIRWlqLpKq0dE_0",
        "role": "member",
        "type": "user"
      }
    ]
  }'

Generated from the API spec

Response

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"
    }
  ]
}

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

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

PUT kbn:/api/agent_builder/conversations/CONVERSATION_ID/access_control
{
  "access_mode": "private",
  "entries": []
}

Generated from the API spec

curl Shell

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": []
  }'

Generated from the API spec

Response

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"
    }
  ]
}

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

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