Postman teams API
The teams API from Postman — 6 operation(s) for teams.
The teams API from Postman — 6 operation(s) for teams.
openapi: 3.1.0
info:
title: Postman Teams API
version: 1.0.0
description: 'Operations tagged teams across 2 of this provider''s published API definitions: postman-api-openapi.yml, postman-teams-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
tags:
- name: teams
paths:
/teams:
get:
operationId: getTeams
summary: Get all teams
description: Gets all Postman teams in your organization.
tags:
- teams
parameters:
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: limit
in: query
description: The maximum number of rows to return in the response.
required: false
schema:
$ref: '#/components/schemas/limitDefault50'
default: 50
- name: settings
in: query
description: If true, returns team settings in the response.
required: false
schema:
$ref: '#/components/schemas/teamSettingsQuery'
default: false
- name: userRoles
in: query
description: If true, returns the team's assigned user roles in the response.
required: false
schema:
$ref: '#/components/schemas/userRolesQuery'
default: false
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Teams_getTeams_Response_200'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTeamsRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
post:
operationId: createTeam
summary: Create a team
description: '[Creates](https://learning.postman.com/docs/administration/managing-your-team/create-teams/) a Postman team in your organization.
'
tags:
- teams
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createGetTeamResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTeamRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createTeam'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/teams/{teamId}:
get:
operationId: getTeam
summary: Get a team
description: Gets information about a Postman team.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: include
in: query
description: 'Include additional information in the request''s response:
- `members` — Include all users and groups, including groups that represent other teams or the entire organization, with access to the team''s entities. This includes team managers, members, and persons invited to collaborate as guests.
- `userRoles` — Include all the team''s user roles in the response.
'
required: false
schema:
$ref: '#/components/schemas/teamsInclude'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createGetTeamResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTeamRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/teams/{teamId}/access-requests:
get:
operationId: getTeamAccessRequests
summary: Get a team's access requests
description: Gets a team's pending access requests.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: limit
in: query
description: The maximum number of rows to return in the response.
required: false
schema:
$ref: '#/components/schemas/limitDefault50'
default: 50
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getTeamAccessRequests'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTeamAccessRequestsRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
post:
operationId: createAccessRequest
summary: Create an access request
description: 'Creates an access request for a team. Access requests include actions such as request to join a team, upgrading a user''s role, adding members, and requesting team role access to another team.
**Note:**
If a team discovery is enabled, the team''s access request is automatically approved.
'
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createAccessRequestResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccessRequestRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createAccessRequest'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/teams/{teamId}/access-requests/{requestId}:
post:
operationId: approveDenyAccessRequest
summary: Approve or deny an access request
description: Approve or deny a team's access request.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: requestId
in: path
description: The access request's ID.
required: true
schema:
$ref: '#/components/schemas/accessRequestId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/approveDenyAccessRequestResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApproveDenyAccessRequestRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/approveDenyAccessRequest'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/teams/{teamId}/bulk-members:
post:
operationId: manageTeamMemberRoles
summary: Manage team member roles
description: 'Adds or removes member roles in groups, teams, organizations, as well as individual users'' roles.
**Note:**
If you remove a role from a group or team, then all members lose the that role''s permissions.
'
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/manageTeamMemberRolesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ManageTeamMemberRolesRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/manageTeamMemberRoles'
delete:
operationId: removeTeamMembers
summary: Remove team members
description: Removes entities, such as users or organizations, from your Postman team. On success, this returns an HTTP `204 No Content` response.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: identifierType
in: header
description: Use SCIM user and group IDs instead of Postman user IDs.
required: false
schema:
$ref: '#/components/schemas/identifierType'
responses:
'204':
description: Remove Team Member
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveTeamMembersRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/removeTeamMembers'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/teams/{teamId}/settings:
get:
operationId: getTeamSettings
summary: Get a team's settings
description: Gets a team's settings.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createGetTeamSettingsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTeamSettingsRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
put:
operationId: updateTeamSettings
summary: Update team settings
description: Updates a team's settings.
tags:
- teams
parameters:
- name: teamId
in: path
description: The team's ID.
required: true
schema:
$ref: '#/components/schemas/teamId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createGetTeamSettingsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamSettingsRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/teamsError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateTeamSettings'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
components:
schemas:
UpdateTeamSettingsSettingsRfaForAddCollaborator:
type: string
enum:
- enabled
- disabled
description: If enabled, collaborators require approval before they can access the team's workspaces.
title: UpdateTeamSettingsSettingsRfaForAddCollaborator
CreateGetTeamResponseTeam:
type: object
properties:
createdAt:
type: string
format: date-time
description: The date and time at which the team was created.
updatedAt:
type: string
format: date-time
description: The date and time at which the team was last updated.
id:
type: integer
description: The team's ID.
name:
type: string
description: The team's name.
handle:
type: string
description: The team's handle.
description:
type: string
description: A description about the team.
organizationId:
type: integer
description: The team's organization ID.
createdBy:
$ref: '#/components/schemas/CreateGetTeamResponseTeamCreatedBy'
description: The user ID of the user who created the team.
enabled:
type: boolean
description: If true, the team is active.
description: Information about the team.
title: CreateGetTeamResponseTeam
getTeamAccessRequests:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GetTeamAccessRequestsDataItems'
description: A list of access requests.
metadata:
$ref: '#/components/schemas/metaDataNextCursor'
title: getTeamAccessRequests
TeamsErrorDetailInvalidEntriesResultItemsEntityId:
oneOf:
- type: integer
- type: string
description: The entity ID.
title: TeamsErrorDetailInvalidEntriesResultItemsEntityId
ApproveDenyAccessRequestResponseResult:
type: object
properties:
entityType:
type: string
description: The entity type.
entityId:
$ref: '#/components/schemas/ApproveDenyAccessRequestResponseResultEntityId'
description: The entity's ID.
role:
type: string
description: The requested team role.
previousRole:
type:
- string
- 'null'
description: The entity's previous role. This value only returns if the entity's role is modified.
status:
type: string
description: The access request's status.
accessRequest:
$ref: '#/components/schemas/ApproveDenyAccessRequestResponseResultAccessRequest'
description: Information about the access request.
description: Information about the approved or denied access request.
title: ApproveDenyAccessRequestResponseResult
CreateTeamRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: CreateTeamRequestBadRequestError
GetTeamAccessRequestsDataItemsCreatedBy:
oneOf:
- type: integer
- type: string
description: The user ID of the user who created the access request.
title: GetTeamAccessRequestsDataItemsCreatedBy
UpdateTeamSettingsSettingsRfaForAddMember:
type: string
enum:
- enabled
- disabled
description: If enabled, admins must approve any new team members before they can join.
title: UpdateTeamSettingsSettingsRfaForAddMember
createAccessRequestResponse:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/teamsAccessRequestData'
title: createAccessRequestResponse
manageTeamMemberRolesRemove:
type: object
properties:
users:
$ref: '#/components/schemas/usersInfo'
groups:
$ref: '#/components/schemas/userGroupsInfo'
orgs:
$ref: '#/components/schemas/orgsInfo'
teams:
$ref: '#/components/schemas/teamsInfo'
description: Information about the bulk `remove` operation.
title: manageTeamMemberRolesRemove
CreateAccessRequestRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: CreateAccessRequestRequestBadRequestError
ApproveDenyAccessRequestRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: ApproveDenyAccessRequestRequestBadRequestError
teamId:
type: integer
title: teamId
CreateAccessRequestRequestType:
type: string
enum:
- REQUEST_TO_ADD_MEMBERS
- REQUEST_TO_JOIN
- UPGRADE_ROLE
description: The type of access request.
title: CreateAccessRequestRequestType
GetTeamsRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: GetTeamsRequestBadRequestError
ApproveDenyAccessRequestAction:
type: string
enum:
- approve
- deny
description: Whether to approve or deny the access request.
title: ApproveDenyAccessRequestAction
teamsInclude:
type: string
enum:
- members
- userRoles
title: teamsInclude
TeamsErrorDetailError:
type: object
properties:
name:
type: string
description: The error name.
message:
type: string
description: The error message.
description: Information about the error.
title: TeamsErrorDetailError
TeamsErrorDetail:
oneOf:
- $ref: '#/components/schemas/teamsErrorDetail'
- $ref: '#/components/schemas/teamsErrorDetailInvalidEntries'
title: TeamsErrorDetail
TeamEntityInfoEntityType:
type: string
enum:
- user
- group
- team
- organization
description: The entity type.
title: TeamEntityInfoEntityType
teamsInfo:
type: object
properties:
'{{teamId}}':
type: array
items:
$ref: '#/components/schemas/teamRoles'
description: A list of the team's roles. The array's name is the team's ID.
title: teamsInfo
removeTeamMembers:
type: object
properties:
entities:
type: array
items:
$ref: '#/components/schemas/teamEntityInfo'
description: A list of entities to remove.
title: removeTeamMembers
CreateGetTeamSettingsResponseSettings:
type: object
properties:
rfa_for_add_member:
type: string
description: If enabled, admins must approve any new team members before they can join.
rfa_for_add_collaborator:
type: string
description: If enabled, collaborators require approval before they can access the team's workspaces.
title: CreateGetTeamSettingsResponseSettings
ApproveDenyAccessRequestResponseResultEntityId:
oneOf:
- type: integer
- type: string
description: The entity's ID.
title: ApproveDenyAccessRequestResponseResultEntityId
teamsAccessRequestData:
type: object
properties:
entityType:
type: string
description: The entity type.
entityId:
$ref: '#/components/schemas/TeamsAccessRequestDataEntityId'
description: The entity's ID.
role:
type: string
description: The entity's role.
previousRole:
type:
- string
- 'null'
description: The entity's previous role. This value only returns if the entity's role is modified.
status:
type: string
description: The request's status.
reason:
type: string
description: The reason for the access request. This only returns if there's an issue with the request.
title: teamsAccessRequestData
createTeam:
type: object
properties:
name:
type: string
description: The team's name. Accepts only alphanumeric characters and spaces.
description:
type:
- string
- 'null'
description: The team's description.
title: createTeam
userGroupsInfo:
type: object
properties:
'{{userGroupId}}':
type: array
items:
$ref: '#/components/schemas/teamRoles'
description: A list of the user group's roles. The array's name is the group's ID.
title: userGroupsInfo
RemoveTeamMembersRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: RemoveTeamMembersRequestBadRequestError
GetTeamSettingsRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: GetTeamSettingsRequestBadRequestError
GetTeamRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: GetTeamRequestBadRequestError
teamsError:
type: object
properties:
type:
type: string
format: uri-reference
description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
status:
type: integer
description: The HTTP status code generated by the origin server.
title:
type: string
description: A short summary of the problem.
detail:
$ref: '#/components/schemas/TeamsErrorDetail'
instance:
type: string
description: The URI reference that identifies the specific occurrence of the problem.
title: teamsError
approveDenyAccessRequest:
type: object
properties:
action:
$ref: '#/components/schemas/ApproveDenyAccessRequestAction'
description: Whether to approve or deny the access request.
required:
- action
title: approveDenyAccessRequest
teamsErrorDetailInvalidEntries:
type: object
properties:
error:
type: string
description: The error message.
result:
type: array
items:
$ref: '#/components/schemas/TeamsErrorDetailInvalidEntriesResultItems'
description: A list of invalid entities.
description: An explanation about the problem.
title: teamsErrorDetailInvalidEntries
ManageTeamMemberRolesRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/teamsError'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
title: ManageTeamMemberRolesRequestBadRequestError
TeamEntityInfoEntityId:
oneOf:
- type: integer
- type: string
description: The entity's ID.
title: TeamEntityInfoEntityId
identifierType:
type: string
title: identifierType
GetTeamAccessRequestsDataItemsRole:
type: string
enum:
- TEAM_MANAGER
- TEAM_DEVELOPER
- TEAM_GUEST_DEVELOPER
- TEAM_GUEST_VIEWER
- TEAM_PARTNER_MANAGER
- TEAM_PARTNER_LEAD
- TEAM_GUEST
- TEAM_PARTNER
- TEAM_COMMUNITY_MANAGER
description: The requested team role.
title: GetTeamAccessRequestsDataItemsRole
TeamDataCreatedBy:
oneOf:
- type: integer
- type: string
description: The user ID of the user who created the team.
title: TeamDataCreatedBy
manageTeamMemberRoles:
type: object
properties:
add:
$ref: '#/components/schemas/manageTeamMemberRolesAdd'
remove:
$ref: '#/components/schemas/manageTeamMemberRolesRemove'
descri
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postman/refs/heads/main/openapi/postman-teams-api-openapi.yml