openapi: 3.1.0 info: title: OpsGenie User API description: >- The OpsGenie User API provides endpoints for managing user accounts within the OpsGenie platform. Developers can create, retrieve, update, and delete users, as well as list users and retrieve escalations associated with specific users. The API supports managing user roles, contact methods, and notification preferences to ensure the right people are reached during incidents. version: '2.0.0' contact: name: Atlassian Support url: https://support.atlassian.com/opsgenie/ termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service externalDocs: description: OpsGenie User API Documentation url: https://docs.opsgenie.com/docs/user-api servers: - url: https://api.opsgenie.com description: Production Server - url: https://api.eu.opsgenie.com description: EU Production Server tags: - name: Users description: >- Operations for creating, retrieving, updating, and deleting user accounts within the OpsGenie platform. security: - genieKey: [] paths: /v2/users: post: operationId: createUser summary: Create user description: >- Creates a new user in the OpsGenie account. tags: - Users requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: operationId: listUsers summary: List users description: >- Returns a list of users in the OpsGenie account. tags: - Users parameters: - name: limit in: query description: >- Maximum number of users to return. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: offset in: query description: >- Starting index for pagination. schema: type: integer minimum: 0 default: 0 - name: sort in: query description: >- Field to sort results by. schema: type: string enum: - username - fullName - insertedAt - name: order in: query description: >- Sort order for results. schema: type: string enum: - asc - desc default: asc - name: query in: query description: >- Query to filter users by username, fullName, or blocked status. schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListUsersResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/users/{identifier}: get: operationId: getUser summary: Get user description: >- Retrieves details of a specific user by ID or username. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetUserResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: operationId: updateUser summary: Update user description: >- Updates the specified user's profile information. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateUserRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: operationId: deleteUser summary: Delete user description: >- Deletes the specified user from the OpsGenie account. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/users/{identifier}/escalations: get: operationId: listUserEscalations summary: List user escalations description: >- Lists the escalation policies that include the specified user. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListUserEscalationsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/users/{identifier}/teams: get: operationId: listUserTeams summary: List user teams description: >- Lists the teams that the specified user belongs to. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListUserTeamsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/users/{identifier}/schedules: get: operationId: listUserSchedules summary: List user schedules description: >- Lists the on-call schedules that include the specified user. tags: - Users parameters: - $ref: '#/components/parameters/UserIdentifier' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListUserSchedulesResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: genieKey: type: apiKey in: header name: Authorization description: >- API key authentication using the GenieKey scheme. parameters: UserIdentifier: name: identifier in: path required: true description: >- Identifier of the user, which can be the user ID or username (email). schema: type: string schemas: CreateUserRequest: type: object required: - username - fullName - role properties: username: type: string format: email description: >- Email address of the user, used as the login identifier. fullName: type: string description: >- Full name of the user. role: type: object description: >- Role assigned to the user. properties: id: type: string description: >- Role ID. name: type: string enum: - Owner - Admin - User - Observer - Stakeholder description: >- Role name. skypeUsername: type: string description: >- Skype username of the user. timeZone: type: string description: >- Timezone of the user, e.g. America/New_York. locale: type: string description: >- Locale of the user, e.g. en_US. userAddress: type: object description: >- Physical address of the user. properties: country: type: string description: >- Country of the user. state: type: string description: >- State or province of the user. city: type: string description: >- City of the user. line: type: string description: >- Street address line. zipCode: type: string description: >- ZIP or postal code. tags: type: array description: >- Tags associated with the user. items: type: string details: type: object description: >- Custom key-value details for the user. additionalProperties: type: array items: type: string invitationDisabled: type: boolean description: >- If true, the user will not receive an invitation email. UpdateUserRequest: type: object properties: fullName: type: string description: >- Full name of the user. role: type: object description: >- Role assigned to the user. properties: id: type: string description: >- Role ID. name: type: string description: >- Role name. skypeUsername: type: string description: >- Skype username of the user. timeZone: type: string description: >- Timezone of the user. locale: type: string description: >- Locale of the user. userAddress: type: object description: >- Physical address of the user. properties: country: type: string description: >- Country. state: type: string description: >- State or province. city: type: string description: >- City. line: type: string description: >- Street address line. zipCode: type: string description: >- ZIP or postal code. tags: type: array description: >- Tags associated with the user. items: type: string details: type: object description: >- Custom key-value details for the user. additionalProperties: type: array items: type: string User: type: object properties: id: type: string description: >- Unique identifier of the user. username: type: string format: email description: >- Email address and login identifier. fullName: type: string description: >- Full name of the user. role: type: object properties: id: type: string description: >- Role ID. name: type: string description: >- Role name. description: >- Role of the user. blocked: type: boolean description: >- Whether the user is blocked. verified: type: boolean description: >- Whether the user has verified their account. timeZone: type: string description: >- Timezone of the user. locale: type: string description: >- Locale of the user. createdAt: type: string format: date-time description: >- Date and time when the user was created. mutedUntil: type: string format: date-time description: >- Date and time until which the user is muted. tags: type: array items: type: string description: >- Tags associated with the user. details: type: object additionalProperties: type: array items: type: string description: >- Custom details for the user. ListUsersResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/User' description: >- List of users. totalCount: type: integer description: >- Total number of users matching the query. paging: type: object properties: next: type: string description: >- URL for the next page of results. first: type: string description: >- URL for the first page. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. GetUserResponse: type: object properties: data: $ref: '#/components/schemas/User' took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. ListUserEscalationsResponse: type: object properties: data: type: array items: type: object properties: id: type: string description: >- Escalation ID. name: type: string description: >- Escalation name. description: >- List of escalations the user belongs to. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. ListUserTeamsResponse: type: object properties: data: type: array items: type: object properties: id: type: string description: >- Team ID. name: type: string description: >- Team name. description: >- List of teams the user belongs to. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. ListUserSchedulesResponse: type: object properties: data: type: array items: type: object properties: id: type: string description: >- Schedule ID. name: type: string description: >- Schedule name. description: >- List of schedules the user belongs to. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. SuccessResponse: type: object properties: result: type: string description: >- Result message. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request. ErrorResponse: type: object properties: message: type: string description: >- Error message. took: type: number description: >- Time taken in seconds. requestId: type: string description: >- Unique identifier for the request.