@spec agents(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1ThreadsThreadAgents.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List agents in a thread

Returns the agents participating in the specified thread. Only personal user threads (threads owned by a single user, not a team) expose agents through this endpoint; requests for team threads return 404.

The authenticated user must have visibility into the thread. Each agent entry includes display information such as name and profile picture. Thread-level overrides (e.g. a custom name or profile picture set for this thread) take precedence over the agent's default values. When the caller is the thread owner, each entry also includes an agent_config object describing the agent's message policy and context configuration.

Successful response

@spec artifacts(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1ThreadsThreadArtifacts.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List artifacts for a thread

Returns all artifacts produced during a thread's AI conversation. Artifacts are structured outputs such as code files, documents, or generated assets created by the AI agent in response to messages in the thread.

The authenticated user must have access to the specified thread. Results are returned in a single page; there is no cursor-based pagination for this endpoint.

Successful response

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete a thread

Permanently deletes a thread and all of its messages and artifacts. This action cannot be undone.

The authenticated user must own the thread or be an owner of the team the thread belongs to. Attempting to delete a thread owned by another user or team returns 403.

Empty response on successful deletion.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Thread.t()} | {:error, ArchAstro.Error.reason()}

Retrieve a thread

Returns the full thread record for the given thread ID. The authenticated user must own the thread or be a member of the workspace it belongs to.

Use this endpoint to fetch the current state of a single thread, including its title, description, and metadata. To list many threads, use the list endpoint with cursor-based pagination.

The requested thread object.

@spec mark_read(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1ThreadsThreadMarkRead.Input.t()
) :: {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Mark a thread as read

Records that a user has read up to a specific message in the thread. Unread indicators and badge counts are cleared up to the specified message.

You must supply exactly one of last_read_message or use_latest_message. Omitting both returns 400. If use_latest_message is true and the thread has no messages, the request succeeds silently with no state change.

For server-to-server (S2S) requests where no user identity is present in the token, the user param is required to identify whose read state to update.

Empty response on success.

@spec messages(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ThreadsThreadMessages.Params.t()
) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1ThreadsThreadMessages.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List messages in a thread

Returns a cursor-paginated list of messages belonging to the specified thread, ordered from oldest to newest. Supply before_cursor, after_cursor, or both to page through or bound the result set; omit both to receive the most recent page. Supply anchor and direction to fetch a window before, after, or around a specific message. Use anchor=last_matching&anchor_agent_mode=embedded to resolve the anchor from the latest embedded-agent message, and add anchor_agent to scope that resolution to a single sender agent. Supply metadata as a JSON-encoded structured expression to filter message metadata before cursor pagination or anchored window limits are applied.

The authenticated user must have access to the thread's owner (workspace or user). A 403 is returned if the thread exists but is not accessible to the caller; a 404 is returned if the thread does not exist or is not visible to the authenticated user.

Pass include_reply_counts: true to annotate each message with the number of threaded replies it has received. This adds a small amount of latency and should be omitted when reply counts are not needed.

Successful response

@spec picture(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PutApiV1ThreadsThreadPicture.Input.t()
) :: {:ok, ArchAstro.Types.Thread.t()} | {:error, ArchAstro.Error.reason()}

Update a thread's profile picture

Uploads a new profile picture for the specified thread and returns the updated thread object. The image must be supplied as a base64-encoded string with its MIME type.

The authenticated user must own the thread or be a team owner of the workspace the thread belongs to. Supplying invalid base64 data returns 422.

The thread object after the profile picture has been updated.

@spec read_status(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ThreadsThreadReadStatus.Params.t()
) ::
  {:ok, ArchAstro.Types.ThreadReadStatus.t()}
  | {:error, ArchAstro.Error.reason()}

Retrieve a thread's read status

Returns the read status of a thread for the specified user, including the ID of the last message they have read and the number of unread messages remaining.

For user-authenticated requests, the status is always returned for the authenticated user and the user parameter is ignored. For server-to-server (S2S) requests, the user parameter is required and must be a valid user ID.

Returns 404 if the thread does not exist or the caller does not have access to it.

The read status record for the requested thread and user.

@spec replace(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PutApiV1ThreadsThread.Input.t()
) :: {:ok, ArchAstro.Types.Thread.t()} | {:error, ArchAstro.Error.reason()}

Update a thread

Updates one or more mutable properties of the specified thread and returns the full thread object with the applied changes. Only the fields you provide are modified; omitted fields retain their current values.

If profile_picture is supplied, the image is uploaded before the other fields are saved, after all ordinary thread fields have passed validation. Supplying invalid base64 picture data returns 422 and no other fields are updated.

Visibility can only widen: private may become restricted or team, and restricted may become team. The authenticated viewer must have permission to modify the thread.

Mirror-thread titles, descriptions, and notification state remain editable by privileged app viewers. Mirror metadata, visibility, and membership are provider-managed and cannot be changed through this endpoint.

The thread object after the update has been applied.

@spec search(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ThreadsThreadSearch.Params.t()
) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1ThreadsThreadSearch.Response.t()}
  | {:error, ArchAstro.Error.reason()}

Search messages in a thread

Searches canonical message content in the specified thread. "text" mode performs the existing case-insensitive substring search, "embedding" ranks stored message embeddings by cosine similarity, and "hybrid" combines the text and embedding rankings with Reciprocal Rank Fusion (RRF). Only messages visible to the authenticated caller are considered.

Results are intentionally lean: each row contains only a bounded content snippet, sender identity, and timestamp. Attachments, reactions, ACLs, and metadata are neither hydrated nor serialized. At most 20 results are returned. Text results support chronological cursor pagination. Embedding and hybrid results are relevance-ranked single pages and return null cursors.

Successful response

@spec trajectories(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ThreadsThreadTrajectories.Params.t()
) ::
  {:ok,
   ArchAstro.Types.Operations.GetApiV1ThreadsThreadTrajectories.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List trajectories for a thread

Returns a cursor-paginated list of thread message trajectories associated with the specified thread. Each trajectory links a user message and its agent response to the underlying AI trajectory record that captured the model's reasoning steps.

The authenticated user must own the thread or be a member of the workspace it belongs to. Results are returned in reverse chronological order by default. Use before_cursor and after_cursor to navigate pages; provide at most one cursor per request.

Optionally filter results to trajectories produced in response to a specific message by supplying the message parameter. When no trajectories match the query, data is an empty array and both cursor fields are null.

Successful response