OpsGenie User API

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.