> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a team > Create a new team or update an existing one using the provided TeamManifest. Matching is by name — if the name matches an existing team it is updated, otherwise a new one is created. ## OpenAPI ````yaml /openapi.json put /api/svc/v1/teams openapi: 3.1.0 info: title: TrueFoundry API description: API for TrueFoundry version: 0.1.0 contact: {} servers: - url: https://{controlPlaneURL} variables: controlPlaneURL: default: app.truefoundry.com description: Control Plane URL security: [] tags: - name: Agent - name: Agent Skills - name: Applications - name: Metrics - name: Apply - name: Artifacts - name: Audit Logs - name: Clusters - name: Jobs - name: Logs - name: MCP Servers V2 - name: MLRepos - name: Model Deployments - name: Models - name: Personal Access Tokens - name: Prompts - name: Provider Integrations - name: SCIM v2 - name: Secret Groups - name: Secrets - name: Teams - name: Traces - name: Users - name: Virtual Accounts - name: Role Bindings - name: Workspaces paths: /api/svc/v1/teams: put: tags: - Teams summary: Create or update a team description: >- Create a new team or update an existing one using the provided TeamManifest. Matching is by name — if the name matches an existing team it is updated, otherwise a new one is created. operationId: Teams.createOrUpdateTeam parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplyTeamRequest' responses: '200': description: The created or updated team. content: application/json: schema: $ref: '#/components/schemas/GetTeamResponse' '409': description: Conflict — the default "everyone" team cannot be edited. content: application/json: schema: $ref: '#/components/schemas/HttpError' '422': description: >- Unprocessable Entity — manifest validation failed, team name is not unique, members are duplicated, or emails are invalid. content: application/json: schema: $ref: '#/components/schemas/HttpError' security: - jwt: [] - jwt: [] components: schemas: ApplyTeamRequest: type: object properties: manifest: oneOf: - $ref: '#/components/schemas/TeamManifest' description: The team manifest describing the team to create or update. dryRun: type: boolean default: false description: When true, validate the request without persisting any changes. nullable: true required: - manifest title: ApplyTeamRequest x-fern-type-name: ApplyTeamRequest GetTeamResponse: type: object properties: data: description: The requested team. allOf: - $ref: '#/components/schemas/Team' required: - data title: GetTeamResponse x-fern-type-name: GetTeamResponse HttpError: type: object properties: statusCode: type: integer description: HTTP Status Code message: type: string description: Error Message code: oneOf: - type: integer - type: string description: Error code nullable: true details: type: array description: Error details items: type: object nullable: true required: - statusCode - message title: HttpError x-fern-type-name: HttpError TeamManifest: type: object required: - type - name - members properties: type: description: +value=team type: string enum: - team name: description: Name of the Team type: string pattern: ^[a-zA-Z][a-zA-Z0-9_-]{1,48}[a-zA-Z0-9]$ displayName: description: >- A human-readable label for the team in the UI. If omitted, the team name is shown. type: string maxLength: 128 description: description: A short description of the team and its purpose. type: string maxLength: 1024 managers: description: >- Emails of each of the user who can manage the members of the team. Any tenant admin is by default a team manager. type: array items: type: string members: description: >- Enter email of each user to add to the team. Use an empty list for a team with no members yet. type: array items: type: string ownedBy: $ref: '#/components/schemas/TeamOwnedBy' tags: description: >- Key-value pairs to categorize this Team (e.g., by owner or environment). type: object identity_provider_mapping: description: Mappings from external identity provider claim value to this team type: array items: $ref: '#/components/schemas/IdentityProviderMapping' title: TeamManifest x-fern-type-name: TeamManifest Team: type: object properties: id: type: string description: System-generated team ID. example: jqfwg345gi25n5ju2yz5iz6m description: type: string description: A short description of the team. tenantName: type: string description: Tenant the team belongs to. accountId: type: string nullable: false description: System-generated ID of the account that owns the team. createdBySubject: description: The subject (user or service account) that created the team. allOf: - $ref: '#/components/schemas/Subject' members: nullable: true description: Email addresses of team members. type: array items: type: string createdAt: format: date-time type: string description: Timestamp when the team was created. updatedAt: format: date-time type: string description: Timestamp when the team was last updated. manifest: oneOf: - $ref: '#/components/schemas/TeamManifest' description: The team manifest defining name, members, managers, and ownership. metadata: nullable: true description: SCIM-related metadata for the team. allOf: - $ref: '#/components/schemas/TeamMetadata' isEditable: type: boolean description: >- Whether the team can be edited. SCIM-managed teams may be non-editable. roles: nullable: true description: Role names assigned to the team. type: array items: type: string required: - id - description - tenantName - accountId - createdBySubject - createdAt - updatedAt - manifest - isEditable title: Team x-fern-type-name: Team TeamOwnedBy: description: Names of the owners that own the team type: object required: - account properties: account: description: The name of the account that owns the team type: string title: TeamOwnedBy x-fern-type-name: TeamOwnedBy IdentityProviderMapping: description: Configuration for mapping IdP claim values to this virtual account type: object required: - identity_provider - value properties: identity_provider: description: Name of the external identity provider type: string value: description: Claim value that should resolve to this virtual account type: string title: IdentityProviderMapping x-fern-type-name: IdentityProviderMapping Subject: type: object properties: subjectId: type: string description: Subject ID subjectType: description: Subject type allOf: - $ref: '#/components/schemas/SubjectType' subjectSlug: type: string description: Subject slug nullable: true subjectDisplayName: type: string description: Subject display name nullable: true subjectPatName: type: string description: Subject PAT name nullable: true subjectControllerName: type: string nullable: true subjectExternalIdentitySlug: type: string description: External identity slug (external_identity_id:sub:email) nullable: true required: - subjectId - subjectType title: Subject x-fern-type-name: Subject TeamMetadata: type: object properties: createdByScim: type: boolean nullable: true scimExternalId: type: string nullable: true title: TeamMetadata x-fern-type-name: TeamMetadata SubjectType: type: string enum: - user - team - serviceaccount - virtualaccount - external-identity - agent-identity - role description: >- Type of the authenticated subject. "user" for human users, "serviceaccount" (also known as virtual account) for programmatic access. title: SubjectType x-fern-type-name: SubjectType securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT ````