Class ThreadResource

constructor

• new ThreadResource(http: HttpClient): ThreadResource

  Parameters

  • http: HttpClient

  Returns ThreadResource

Readonlymembers

Readonlysettings

agents

• agents(thread: string): Promise<{ data: Record<string, unknown>[] }>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). Must be a personal user thread visible to the authenticated user.

  Returns Promise<{ data: Record<string, unknown>[] }>

  Successful response

artifacts

• artifacts(
      thread: string,
  ): Promise<
      {
          data: {
              agent?: string;
              content_type?: string;
              created_at?: string;
              current_version?: string;
              description?: string;
              file?: string;
              file_name?: string;
              file_url?: string;
              id: string;
              image_source?: {
                  file?: string;
                  height?: number;
                  media?: string;
                  mime_type?: string;
                  refresh_url?: string;
                  url?: string;
                  width?: number;
              };
              name?: string;
              org?: string;
              sandbox?: string;
              team?: string;
              thread?: string;
              updated_at?: string;
              user?: string;
              version?: number;
          }[];
      },
  >

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). Must be accessible to the authenticated user.

  Returns Promise<
      {
          data: {
              agent?: string;
              content_type?: string;
              created_at?: string;
              current_version?: string;
              description?: string;
              file?: string;
              file_name?: string;
              file_url?: string;
              id: string;
              image_source?: {
                  file?: string;
                  height?: number;
                  media?: string;
                  mime_type?: string;
                  refresh_url?: string;
                  url?: string;
                  width?: number;
              };
              name?: string;
              org?: string;
              sandbox?: string;
              team?: string;
              thread?: string;
              updated_at?: string;
              user?: string;
              version?: number;
          }[];
      },
  >

  Successful response

delete

• delete(thread: string): Promise<void>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). The authenticated user must own this thread.

  Returns Promise<void>

  Empty response on successful deletion.

get

• get(thread: string): Promise<Thread>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). The authenticated user must have access to this thread.

  Returns Promise<Thread>

  The requested thread object.

markRead

• markRead(
      thread: string,
      input: {
          last_read_message?: string;
          use_latest_message?: boolean;
          user?: string;
      },
  ): Promise<void>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). The thread to mark as read.

  • input: { last_read_message?: string; use_latest_message?: boolean; user?: string }

    Request body.

    • Optionallast_read_message?: string

      Message ID (msg_...) to record as the last read message. Mutually exclusive with use_latest_message.

    • Optionaluse_latest_message?: boolean

      When true, marks the thread as read up to the latest message. Mutually exclusive with last_read_message.

    • Optionaluser?: string

      User ID (usr_...) whose read state to update. Required for S2S requests; ignored when an authenticated user is present in the token.

  Returns Promise<void>

  Empty response on success.

messages

• messages(
      thread: string,
      params?: {
          afterCursor?: string;
          afterLimit?: number;
          anchor?: string;
          anchorAgent?: string;
          anchorAgentMode?: "cli" | "embedded";
          beforeCursor?: string;
          beforeLimit?: number;
          direction?: "before" | "after" | "around";
          includeAnchor?: boolean;
          includeReplyCounts?: boolean;
          limit?: number;
      },
  ): Promise<
      {
          data: {
              after_cursor?: string;
              anchor?: string;
              before_cursor?: string;
              messages: {
                  actors?: {
                      alias?: string;
                      id?: string;
                      name?: string;
                      profile_picture?: {
                          file?: (...)
                          | (...);
                          height?: (...) | (...);
                          media?: (...) | (...);
                          mime_type?: (...) | (...);
                          refresh_url?: (...) | (...);
                          url?: (...) | (...);
                          width?: (...) | (...);
                      };
                  }[];
                  agent?: string;
                  agent_mode?: "cli"
                  | "embedded";
                  attachments?: {
                      content_type?: string;
                      description?: string;
                      filename?: string;
                      height?: number;
                      id: string;
                      image_height?: number;
                      image_source?: {
                          file?: (...) | (...);
                          height?: (...) | (...);
                          media?: (...) | (...);
                          mime_type?: (...) | (...);
                          refresh_url?: (...) | (...);
                          url?: (...) | (...);
                          width?: (...) | (...);
                      };
                      image_url?: string;
                      image_width?: number;
                      media_type?: string;
                      name?: string;
                      object?: Record<string, unknown>;
                      title?: string;
                      type: string;
                      url?: string;
                      variants?: {
                          content_type?: ...;
                          created_at?: ...;
                          file?: ...;
                          filename?: ...;
                          height?: ...;
                          id: ...;
                          image_source?: ...;
                          updated_at?: ...;
                          url?: ...;
                          variant_key?: ...;
                          width?: ...;
                      }[];
                      version?: number;
                      width?: number;
                  }[];
                  branched_thread?: string;
                  content?: string;
                  created_at?: string;
                  has_replies?: boolean;
                  id: string;
                  idempotency_key?: string;
                  legacy_agent?: string;
                  metadata?: Record<string, unknown>;
                  org?: string;
                  reactions?: {
                      payload?: Record<string, unknown>;
                      type: string;
                      user?: string;
                  }[];
                  rendering_mode?: string;
                  replies?: Record<string, unknown>[];
                  replies_after_cursor?: string;
                  replies_before_cursor?: string;
                  reply_count?: number;
                  reply_to?: Record<string, unknown>;
                  sandbox?: string;
                  team?: string;
                  thread?: string;
                  user?: string;
              }[];
          };
      },
  >

  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. 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.

  Parameters

  • thread: string

    Thread ID (thr_...). The authenticated user must have access to this thread.

  • Optionalparams: {
        afterCursor?: string;
        afterLimit?: number;
        anchor?: string;
        anchorAgent?: string;
        anchorAgentMode?: "cli" | "embedded";
        beforeCursor?: string;
        beforeLimit?: number;
        direction?: "before" | "after" | "around";
        includeAnchor?: boolean;
        includeReplyCounts?: boolean;
        limit?: number;
    }

    Query parameters.

    • OptionalafterCursor?: string

      Opaque cursor returned in a previous response's after_cursor field. When provided, returns messages immediately after that position. May be combined with before_cursor to bound a range.

    • OptionalafterLimit?: number

      For direction=around, maximum number of messages newer than the anchor. Defaults to 20.

    • Optionalanchor?: string

      Message ID (msg_...) to use as a window anchor, or last_matching to resolve the anchor from the latest message matching the anchor filters. Cannot be combined with before_cursor or after_cursor.

    • OptionalanchorAgent?: string

      When anchor=last_matching, scope the anchor resolution to messages sent by this agent (agi_...). Combine with anchor_agent_mode to resolve the latest message from a specific agent in a given mode.

    • OptionalanchorAgentMode?: "cli" | "embedded"

      When anchor=last_matching, resolve the anchor from the latest message with this local agent execution mode.

    • OptionalbeforeCursor?: string

      Opaque cursor returned in a previous response's before_cursor field. When provided, returns messages immediately before that position. May be combined with after_cursor to bound a range.

    • OptionalbeforeLimit?: number

      For direction=around, maximum number of messages older than the anchor. Defaults to 20.

    • Optionaldirection?: "before" | "after" | "around"

      Window direction relative to anchor. before returns older messages, after returns newer messages, and around returns messages on both sides. Defaults to after when anchor is supplied. direction=around cannot be combined with an explicit limit; use before_limit and after_limit.

    • OptionalincludeAnchor?: boolean

      Whether to include the anchor message in a window response. Defaults to true for direction=around; ignored for ordinary cursor pagination and one-sided windows.

    • OptionalincludeReplyCounts?: boolean

      When true, each message in the response is annotated with its threaded reply count. Defaults to false. Adds latency; omit when reply counts are not needed.

    • Optionallimit?: number

      Maximum number of messages to return per page. Defaults to 20.

  Returns Promise<
      {
          data: {
              after_cursor?: string;
              anchor?: string;
              before_cursor?: string;
              messages: {
                  actors?: {
                      alias?: string;
                      id?: string;
                      name?: string;
                      profile_picture?: {
                          file?: (...)
                          | (...);
                          height?: (...) | (...);
                          media?: (...) | (...);
                          mime_type?: (...) | (...);
                          refresh_url?: (...) | (...);
                          url?: (...) | (...);
                          width?: (...) | (...);
                      };
                  }[];
                  agent?: string;
                  agent_mode?: "cli"
                  | "embedded";
                  attachments?: {
                      content_type?: string;
                      description?: string;
                      filename?: string;
                      height?: number;
                      id: string;
                      image_height?: number;
                      image_source?: {
                          file?: (...) | (...);
                          height?: (...) | (...);
                          media?: (...) | (...);
                          mime_type?: (...) | (...);
                          refresh_url?: (...) | (...);
                          url?: (...) | (...);
                          width?: (...) | (...);
                      };
                      image_url?: string;
                      image_width?: number;
                      media_type?: string;
                      name?: string;
                      object?: Record<string, unknown>;
                      title?: string;
                      type: string;
                      url?: string;
                      variants?: {
                          content_type?: ...;
                          created_at?: ...;
                          file?: ...;
                          filename?: ...;
                          height?: ...;
                          id: ...;
                          image_source?: ...;
                          updated_at?: ...;
                          url?: ...;
                          variant_key?: ...;
                          width?: ...;
                      }[];
                      version?: number;
                      width?: number;
                  }[];
                  branched_thread?: string;
                  content?: string;
                  created_at?: string;
                  has_replies?: boolean;
                  id: string;
                  idempotency_key?: string;
                  legacy_agent?: string;
                  metadata?: Record<string, unknown>;
                  org?: string;
                  reactions?: {
                      payload?: Record<string, unknown>;
                      type: string;
                      user?: string;
                  }[];
                  rendering_mode?: string;
                  replies?: Record<string, unknown>[];
                  replies_after_cursor?: string;
                  replies_before_cursor?: string;
                  reply_count?: number;
                  reply_to?: Record<string, unknown>;
                  sandbox?: string;
                  team?: string;
                  thread?: string;
                  user?: string;
              }[];
          };
      },
  >

  Successful response

picture

• picture(
      thread: string,
      input: { picture: { data: string; filename: string; mime_type: string } },
  ): Promise<Thread>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). The authenticated user must have permission to update this thread.

  • input: { picture: { data: string; filename: string; mime_type: string } }

    Request body.

    • picture: { data: string; filename: string; mime_type: string }

      Profile picture payload. Must include the base64-encoded image data and its MIME type.

  Returns Promise<Thread>

  The thread object after the profile picture has been updated.

readStatus

• readStatus(
      thread: string,
      params?: { user?: string },
  ): Promise<ThreadReadStatus>

  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.

  Parameters

  • thread: string

    Thread ID (thr_...). Must be accessible to the authenticated user or, for S2S requests, to the specified user.

  • Optionalparams: { user?: string }

    Query parameters.

    • Optionaluser?: string

      User ID (usr_...) whose read status to retrieve. Required for S2S requests; ignored for user-authenticated requests, which always return the status for the authenticated user.

  Returns Promise<ThreadReadStatus>

  The read status record for the requested thread and user.

replace

• replace(
      thread: string,
      input: {
          description?: string;
          metadata?: Record<string, unknown>;
          muted?: boolean;
          profile_picture?: { data?: string; filename?: string; mime_type?: string };
          title?: string;
      },
  ): Promise<Thread>

  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. Supplying invalid base64 picture data returns 422 and no other fields are updated. The authenticated user must own the thread or be a team owner of the workspace the thread belongs to.

  Parameters

  • thread: string

    Thread ID (thr_...). The authenticated user must have permission to update this thread.

  • input: {
        description?: string;
        metadata?: Record<string, unknown>;
        muted?: boolean;
        profile_picture?: { data?: string; filename?: string; mime_type?: string };
        title?: string;
    }

    Request body.

    • Optionaldescription?: string

      Optional longer text describing the thread's purpose. Replaces the existing description when provided.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value metadata to store on the thread. Merged with or replaces existing metadata.

    • Optionalmuted?: boolean

      When true, suppresses notifications for new messages in this thread for the authenticated user.

    • Optionalprofile_picture?: { data?: string; filename?: string; mime_type?: string }

      New profile picture for the thread. Provide all three inner fields to replace the existing image.

    • Optionaltitle?: string

      Human-readable display name for the thread. Replaces the existing title when provided.

  Returns Promise<Thread>

  The thread object after the update has been applied.

search

• search(
      thread: string,
      params?: { q?: string; type?: string },
  ): Promise<{ data: Record<string, unknown>[] }>

  Search context items within a thread Performs a full-text search over context items (messages, files, and other indexed sources) attached to the specified thread. Returns tagged objects whose content matches the query string. Use the type param to restrict results to a particular context source. All accessible context source types are searched when type is omitted. The authenticated user must have access to the thread.

  Parameters

  • thread: string

    Thread ID (thr_...). Must be accessible to the authenticated user.

  • Optionalparams: { q?: string; type?: string }

    Query parameters.

    • Optionalq?: string

      Full-text search query. Results are ranked by relevance to this string.

    • Optionaltype?: string

      Context source type to restrict the search to, e.g. "thread/messages". Omit to search across all context sources for the thread.

  Returns Promise<{ data: Record<string, unknown>[] }>

  Successful response