openapi: 3.2.0
info:
  title: 8x8 Administration Operations API
  version: '1.0'
  description: 'Operation management API providing endpoints to retrieve and track the status of asynchronous operations. Operations are created automatically when asynchronous resource operations (create, update, delete) are initiated.


    The current version of the API is v1.0.


    ## Authentication


    All requests to this API require authentication using an API key. Include your API key in the request header:


    ```

    x-api-key: YOUR_API_KEY

    ```


    ## Versioning


    Specify the API version using the `Accept` header:


    ```

    Accept: application/vnd.operations.v1+json

    ```


    ## Base URL


    `https://api.8x8.com/admin-provisioning`


    ## Endpoints


    | Endpoint | Method | Purpose | Async? |

    |----------|--------|---------|--------|

    | `/operations/{operationId}` | GET | Retrieve the status and details of an asynchronous operation | No |


    ## OpenAPI Specification


    Download the complete OpenAPI specification: [operation-api-v1.yaml](/administration/operation-api-v1.yaml)

    '
servers:
- url: https://api.8x8.com/admin-provisioning
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Operations
paths:
  /operations/{operationId}:
    get:
      operationId: getOperation
      summary: Get operation by ID
      description: 'Retrieves the current status and details of an asynchronous operation.

        Operations are used to track the progress of resource creation, updates, and deletions.

        The operation status is polled from the underlying service and updated in real-time.

        '
      tags:
      - Operations
      parameters:
      - name: X-Request-Id
        in: header
        description: Optional request identifier for tracking
        required: false
        schema:
          type: string
          format: uuid
      - name: operationId
        in: path
        description: Unique identifier of the operation
        required: true
        schema:
          type: string
          example: op_123456789
      responses:
        '200':
          description: Successful response with operation details
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/Operation'
              example:
                operationId: op_123456789
                status: COMPLETED
                customerId: 0012J00042NkZQIQA3
                resourceType: USER
                resourceId: hvOB1l3zDCaDAwp9tNLzZA
                operationType: CREATE
                createdTime: '2025-01-01T01:02:03Z'
                completedTime: '2025-01-01T01:05:03Z'
                _links:
                  self:
                    href: https://api.8x8.com/admin-provisioning/operations/op_123456789
                  resource:
                    href: https://api.8x8.com/admin-provisioning/users/hvOB1l3zDCaDAwp9tNLzZA
        '403':
          description: Forbidden - Customer ID mismatch or insufficient permissions
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                title: Not allowed to access data for another customer
                errors:
                - code: FORBIDDEN
                  message: Not allowed to access data for another customer
        '404':
          description: Not Found - Operation does not exist
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: Operation not found
                detail: 'Operation not found: op_unknown'
                errors:
                - code: NOT_FOUND
                  message: 'Operation not found: op_unknown'
        '408':
          description: Request Timeout - Downstream service timeout
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 408
                title: Request Timeout
                errors:
                - code: REQUEST_TIMEOUT
                  message: Request to downstream service timed out
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: Service Unavailable
                errors:
                - code: SERVICE_UNAVAILABLE
                  message: Service is temporarily unavailable
        '429':
          description: Too Many Requests - Rate limit exceeded
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                title: Too Many Requests
                errors:
                - code: TOO_MANY_REQUESTS
                  message: Rate limit exceeded, please try again later
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.operations.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: Internal Server Error
                detail: Internal operation handler configuration error for  CREATE USER
                errors:
                - code: UNKNOWN
                  message: An unexpected error occurred
components:
  schemas:
    Error:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: Field name related to the error
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type:
          - string
          - 'null'
          description: Detailed error message
          example: Operation not found
    Link:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL for the link
          example: https://api.8x8.com/admin-provisioning/operations/op_123456789
    ErrorCode:
      type: string
      enum:
      - UNKNOWN
      - VALIDATION_ERROR
      - FORBIDDEN
      - CONFLICTING_QUERY_PARAMETER
      - SERVICE_UNAVAILABLE
      - NOT_FOUND
      - BAD_REQUEST
      - REQUEST_TIMEOUT
      - TOO_MANY_REQUESTS
      - CONFLICT
      description: Error code indicating the type of error
    OperationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        resource:
          $ref: '#/components/schemas/Link'
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code
          example: 404
        instance:
          type:
          - string
          - 'null'
          description: URI reference that identifies the specific occurrence of the problem
        time:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the error occurred
          example: '2025-01-01T01:02:03Z'
        title:
          type:
          - string
          - 'null'
          description: Short, human-readable summary of the problem
          example: Operation not found
        detail:
          type:
          - string
          - 'null'
          description: Human-readable explanation specific to this occurrence
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Error'
    Operation:
      type: object
      properties:
        operationId:
          type:
          - string
          - 'null'
          description: Unique identifier for the operation
          example: op_123456789
        status:
          type:
          - string
          - 'null'
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          - UNKNOWN
          description: Current status of the operation
          example: PENDING
        customerId:
          type:
          - string
          - 'null'
          description: Customer ID associated with the operation
          example: 0012J00042NkZQIQA3
        resourceType:
          type:
          - string
          - 'null'
          enum:
          - USER
          - RING_GROUP
          - SITE
          description: Type of resource being operated on
          example: USER
        resourceId:
          type:
          - string
          - 'null'
          description: ID of the resource being operated on
          example: hvOB1l3zDCaDAwp9tNLzZA
        operationType:
          type:
          - string
          - 'null'
          enum:
          - CREATE
          - UPDATE
          - DELETE
          description: Type of operation being performed
          example: CREATE
        createdTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the operation was created
          example: '2025-01-01T01:02:03Z'
        completedTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the operation completed
          example: '2025-01-01T01:05:03Z'
        error:
          $ref: '#/components/schemas/ErrorResponse'
        _links:
          $ref: '#/components/schemas/OperationLinks'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key