openapi: 3.1.0
info:
  title: OpsGenie Account Users API
  description: The OpsGenie Account API provides endpoints for retrieving account-level information and configuration settings. Developers can use this API to access details about their OpsGenie account, including plan information and account metadata. It serves as a foundational API for administrative operations and account management within the OpsGenie platform.
  version: 2.0.0
  contact:
    name: Atlassian Support
    url: https://support.atlassian.com/opsgenie/
  termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service
servers:
- url: https://api.opsgenie.com
  description: Production Server
- url: https://api.eu.opsgenie.com
  description: EU Production Server
security:
- genieKey: []
tags:
- name: Users
  description: Operations for creating, retrieving, updating, and deleting user accounts within the OpsGenie platform.
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:
  schemas:
    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.
    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.
    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.
    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.
    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.
    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.
    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.
    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.
    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.
  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
  securitySchemes:
    genieKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication using the GenieKey scheme.
externalDocs:
  description: OpsGenie Account API Documentation
  url: https://docs.opsgenie.com/docs/account-api