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

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.

Successful response

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Teams.Input.t()
) ::
  {:ok, ArchAstro.Types.Team.t()} | {:error, ArchAstro.Error.reason()}

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.

The newly created team.

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

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.

Empty response — the team has been deleted.

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

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.

The requested team, including its members and threads.

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

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.

The newly created team invite containing the join code.

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

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.

Successful response

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

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.

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

@spec join_by_code(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1TeamsJoinByCode.Input.t()
) :: {:ok, ArchAstro.Types.Team.t()} | {:error, ArchAstro.Error.reason()}

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.

The team the principal has joined.

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

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.

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

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

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.

Successful response

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

List task assignees for a team

Returns the list of principals — users and agents — that can be assigned to tasks within the team. Results include both human members and AI agents and are sorted alphabetically by display name.

This endpoint is only available for team-scoped contexts. Calling it with a user-scoped owner returns a 400 error. The authenticated user must be a member of the team or hold org-admin access. App-scoped developer and server-to-server callers may list assignees for teams in their app so they can select the explicit user or agent actor required by privileged task mutations.

Successful response

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

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.

The updated team with all changes applied.