---
search:
  tags:
    - AI
    - POST
seo:
  description: >-
    Search agent threads the caller is allowed to read. Reference for the POST
    /v1/ai/chats/search endpoint in the Roboto REST API.
sidebar:
  label: Search threads legacy
  badge: POST
title: Search threads legacy
type: openapi-operation
---
Search agent threads the caller is allowed to read.

The repo enforces a filter whitelist (``thread_id``, ``title``,
``created``, ``created_by``, ``status``, ``visibility``,
``created_from_agent_id``, ``subject_id``) and a sort whitelist
(``created``). ``status`` accepts the lowercase ``AgentThreadStatus``
values (``not_started``, ``user_turn``, ``roboto_turn``,
``client_tool_turn``, ``goals_failed``); ``visibility`` accepts the
lowercase ``ThreadVisibility`` values (``private``, ``org``).

Two structural authz gates are bound from caller identity and AND-ed
onto every query — both are unreachable from the request body:

* ``org_id`` pins the result set to the caller's org.
* ``visibility = 'org' OR created_by = caller_user_id`` hides
  ``PRIVATE`` threads created by other users; the caller sees every
  ``ORG``-visible thread plus their own private rows. Admins
  (``identity.is_roboto_admin``) bypass this gate so the admin
  thread explorer continues to see every thread in an org —
  mirroring the per-row check in ``get_thread_by_id_with_access_check``.

Common UI compositions: the dataset-detail "Agent Threads" tab pins
``subject_id == <dataset_id>`` as a scope filter; the agent detail
page's "threads launched from this agent" list passes
``created_from_agent_id == <id>``.

### Access control
 - requires_org
 - Restricted tokens need the API scope `api.everything_else`

`POST /v1/ai/chats/search`