Class TeamResource

constructor

• new TeamResource(http: HttpClient): TeamResource

  Parameters

  • http: HttpClient

  Returns TeamResource

Readonlycustom_objects

Readonlymembers

Readonlythreads

artifacts

• artifacts(
      team: 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 a team's artifacts Returns all artifacts owned by the specified team. Artifacts represent AI-generated or user-uploaded files associated with agent sessions, threads, or sandboxes — such as images, documents, and code outputs. The authenticated user must be a member of the team. Attempting to list artifacts for a team the caller does not have access to returns 404 rather than 403 to avoid leaking team existence. Results are returned in a single page without cursor pagination. Each artifact in the response reflects the state of its current version, including a short-lived signed file_url for direct download.

  Parameters

  • team: string

    Team ID (tea_...). The authenticated user must be a member of this team.

  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

create

• create(
      input: {
          acl?: {
              add?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              grants?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              remove?: { principal?: string; principal_type: string }[];
          };
          description?: string;
          metadata?: Record<string, unknown>;
          name: string;
          org?: string;
      },
  ): Promise<Team>

  Create a team Creates a new team and returns the created team object. The authenticated user becomes the team's owner. When app is supplied, the request is scoped to that app and the caller must hold the corresponding app scope. Omit org unless you want the team pinned to a specific organization. A default chat thread is provisioned for the team automatically after creation.

  Parameters

  • input: {
        acl?: {
            add?: { actions: string[]; principal?: string; principal_type: string }[];
            grants?: { actions: string[]; principal?: string; principal_type: string }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        description?: string;
        metadata?: Record<string, unknown>;
        name: string;
        org?: string;
    }

    Request body.

    • Optionalacl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      }

      Access control configuration for the team. Controls who can discover and join the team.

    • Optionaldescription?: string

      Optional human-readable description of the team's purpose.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value pairs you can attach to the team for your own use. Values must be strings.

    • name: string

      Display name for the team.

    • Optionalorg?: string

      Organization ID (org_...) to associate the team with. Omit to create the team without an org affiliation.

  Returns Promise<Team>

  The newly created team.

delete

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

  Delete a team Permanently deletes the team identified by team. This action is irreversible — all team memberships, settings, and associated data are removed. The caller must be the team owner or an org admin. When app is present, the caller must also hold the corresponding app scope.

  Parameters

  • team: string

    Team ID (team_...) of the team to delete.

  Returns Promise<void>

  Empty response — the team has been deleted.

get

• get(team: string): Promise<Team>

  Retrieve a team Returns the full team object for the given team ID, including its current member list and all associated threads. The authenticated user must be a member of the team or hold a role that grants visibility (org admin, app scope). When app is supplied, the caller must hold the corresponding app scope.

  Parameters

  • team: string

    Team ID (team_...) of the team to retrieve.

  Returns Promise<Team>

  The requested team, including its members and threads.

invite

• invite(team: string): Promise<TeamInvite>

  Create a team invite Generates a new invite code for the specified team. The authenticated user must be a member of the team with the owner or admin role. The returned code is a short alphanumeric string that other users can present to join the team. Each call produces a new code; previously issued codes are not invalidated by this request.

  Parameters

  • team: string

    Team ID (tm_...) identifying the team for which to generate the invite code.

  Returns Promise<TeamInvite>

  The newly created team invite containing the join code.

invites

• invites(team: string): Promise<{ code: string }>

  Create a team invite (server-to-server) Generates a new invite code for the specified team using server-to-server authentication. Unlike the user-facing create endpoint, this variant does not require the caller to be a team member — it is intended for privileged back-end services acting on behalf of your platform. The returned code is a short alphanumeric string that users can present to join the team. Each call produces a new code; previously issued codes are not invalidated by this request.

  Parameters

  • team: string

    Team ID (tm_...) identifying the team for which to generate the invite code.

  Returns Promise<{ code: string }>

  Successful response

join

• join(
      team: string,
      input: { agent?: string; email?: string; user?: string },
  ): Promise<void>

  Join a team Adds a principal to a team that is visible to the authenticated user. By default, the currently authenticated user joins the team. Provide agent to add an agent to the team instead — the caller must already be a member of the team to do so. Provide user (by ID) or email to add another user from your organization — the caller must be a team owner, team admin, or org admin. Only one of agent, user, or email may be supplied per request. If the target principal is already a member of the team, the request succeeds without creating a duplicate membership. Server-to-server callers are not permitted to use this endpoint; use the invite-code endpoint instead.

  Parameters

  • team: string

    Team ID (team_...) to join.

  • input: { agent?: string; email?: string; user?: string }

    Request body.

    • Optionalagent?: string

      Agent ID (agent_...) to add to the team. The caller must already be a member of the team.

    • Optionalemail?: string

      Email address of a member of the caller's organization to add to the team. Requires team-owner, team-admin, or org-admin role.

    • Optionaluser?: string

      User ID (user_...) of a member of the caller's organization to add to the team. Requires team-owner, team-admin, or org-admin role.

  Returns Promise<void>

  Empty response — the principal is now a member of the team.

joinByCode

• joinByCode(
      input: {
          agent?: string;
          invite_code?: string;
          join_code?: string;
          user?: string;
      },
  ): Promise<Team>

  Join a team with an invite code Adds a principal to a team using a 12-character invite code. The invite code can be supplied as either join_code or invite_code; both are accepted for backwards compatibility. For user-authenticated requests, the currently authenticated user is added to the team. For server-to-server requests, you must supply either agent (to add an agent) or user (to add a specific user by ID). If the user is already a member of the team, the request succeeds without creating a duplicate membership. This endpoint is rate-limited to 10 requests per minute per IP address to prevent invite-code enumeration.

  Parameters

  • input: { agent?: string; invite_code?: string; join_code?: string; user?: string }

    Request body.

    • Optionalagent?: string

      Agent ID (agent_...) to add to the team. When provided, the agent is joined instead of the authenticated user. Requires a server-to-server session.

    • Optionalinvite_code?: string

      12-character invite code — alias for join_code accepted for backwards compatibility.

    • Optionaljoin_code?: string

      12-character invite code that identifies the team. Mutually usable with invite_code.

    • Optionaluser?: string

      User ID (user_...) to add to the team. Required for server-to-server requests when agent is not supplied.

  Returns Promise<Team>

  The team the principal has joined.

leave

• leave(team: string): Promise<void>

  Leave a team Removes a principal from a team. By default, the authenticated user removes themselves from the team. Provide agent to remove an agent instead — the caller must be a member of the team to do so. Team owners cannot leave their own team. To transfer ownership first, use the update-membership endpoint, then call this endpoint. For server-to-server requests, user is required to identify which user should be removed.

  Parameters

  • team: string

    Team ID (team_...) to leave.

  Returns Promise<void>

  Empty response — the principal has been removed from the team.

list

• list(
      params?: {
          membership?: string;
          metadata?: {
              clause?: Record<string, unknown>;
              clauses?: Record<string, unknown>[];
              key?: string;
              operator?: "and" | "or" | "eq" | "contains" | "exists" | "not";
              path?: string[];
              type?: string;
              value?: unknown;
          };
          page?: number;
          pageSize?: number;
          search?: string;
      },
  ): Promise<
      {
          data: {
              acl?: {
                  add?: {
                      actions: string[];
                      principal?: string;
                      principal_type: string;
                  }[];
                  grants?: {
                      actions: string[];
                      principal?: string;
                      principal_type: string;
                  }[];
                  remove?: { principal?: string; principal_type: string }[];
              };
              app?: string;
              badges?: Record<string, unknown>;
              created_at?: string;
              description?: string;
              id: string;
              membership_status?: string;
              metadata?: Record<string, unknown>;
              name?: string;
              org?: string;
              sandbox?: string;
              slug?: string;
              updated_at?: string;
          }[];
          has_next: boolean;
          has_prev: boolean;
          page: number;
          page_size: number;
          total_entries: number;
          total_pages: number;
      },
  >

  List teams Returns a paginated list of teams visible to the authenticated user, ordered by creation time descending. Use membership to narrow results to teams the caller has joined or teams they are eligible to join based on their ACL visibility. Supports full-text search across team name and description via search, and structured metadata filtering via metadata. When app is present, results are scoped to that app and the caller must hold the corresponding app scope.

  Parameters

  • Optionalparams: {
        membership?: string;
        metadata?: {
            clause?: Record<string, unknown>;
            clauses?: Record<string, unknown>[];
            key?: string;
            operator?: "and" | "or" | "eq" | "contains" | "exists" | "not";
            path?: string[];
            type?: string;
            value?: unknown;
        };
        page?: number;
        pageSize?: number;
        search?: string;
    }

    Query parameters.

    • Optionalmembership?: string

      Filter teams by membership status. "joined" returns only teams the caller is a member of. "joinable" returns ACL-visible teams the caller has not yet joined. Omit to return all visible teams.

    • Optionalmetadata?: {
          clause?: Record<string, unknown>;
          clauses?: Record<string, unknown>[];
          key?: string;
          operator?: "and" | "or" | "eq" | "contains" | "exists" | "not";
          path?: string[];
          type?: string;
          value?: unknown;
      }

      Structured metadata filter expression. Only teams whose metadata satisfies the expression are returned.

    • Optionalpage?: number

      Page number to retrieve, starting at 1. Defaults to 1.

    • OptionalpageSize?: number

      Number of teams to return per page. Defaults to 25.

    • Optionalsearch?: string

      Full-text search string matched against team name and description.

  Returns Promise<
      {
          data: {
              acl?: {
                  add?: {
                      actions: string[];
                      principal?: string;
                      principal_type: string;
                  }[];
                  grants?: {
                      actions: string[];
                      principal?: string;
                      principal_type: string;
                  }[];
                  remove?: { principal?: string; principal_type: string }[];
              };
              app?: string;
              badges?: Record<string, unknown>;
              created_at?: string;
              description?: string;
              id: string;
              membership_status?: string;
              metadata?: Record<string, unknown>;
              name?: string;
              org?: string;
              sandbox?: string;
              slug?: string;
              updated_at?: string;
          }[];
          has_next: boolean;
          has_prev: boolean;
          page: number;
          page_size: number;
          total_entries: number;
          total_pages: number;
      },
  >

  Successful response

update

• update(
      team: string,
      input: {
          acl?: {
              add?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              grants?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              remove?: { principal?: string; principal_type: string }[];
          };
          description?: string;
          metadata?: Record<string, unknown>;
          name?: string;
          profile_picture?: { data?: string; filename?: string; mime_type?: string };
      },
  ): Promise<Team>

  Update a team Updates one or more attributes of the team identified by team. Only the fields you provide are changed; omitted fields are left as-is. To replace the team's profile picture, supply the profile_picture object with base64-encoded image data. The previous picture is deleted after the new one is successfully uploaded. When app is present, the caller must hold the corresponding app scope. The caller must be a team owner or org admin.

  Parameters

  • team: string

    Team ID (team_...) of the team to update.

  • input: {
        acl?: {
            add?: { actions: string[]; principal?: string; principal_type: string }[];
            grants?: { actions: string[]; principal?: string; principal_type: string }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        description?: string;
        metadata?: Record<string, unknown>;
        name?: string;
        profile_picture?: { data?: string; filename?: string; mime_type?: string };
    }

    Request body.

    • Optionalacl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      }

      New access control configuration for the team. Replaces the existing ACL.

    • Optionaldescription?: string

      New human-readable description of the team's purpose.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value pairs to set on the team. Replaces the existing metadata map entirely.

    • Optionalname?: string

      New display name for the team.

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

      New profile picture for the team. Provide this object to upload and replace the current picture.

  Returns Promise<Team>

  The updated team with all changes applied.