openapi: 3.0.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: []
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:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Operation:
      type: object
      properties:
        operationId:
          type: string
          description: Unique identifier for the operation
          example: "op_123456789"
          nullable: true
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETED, FAILED, UNKNOWN]
          description: Current status of the operation
          example: "PENDING"
          nullable: true
        customerId:
          type: string
          description: Customer ID associated with the operation
          example: "0012J00042NkZQIQA3"
          nullable: true
        resourceType:
          type: string
          enum: [USER, RING_GROUP, SITE]
          description: Type of resource being operated on
          example: "USER"
          nullable: true
        resourceId:
          type: string
          description: ID of the resource being operated on
          example: "hvOB1l3zDCaDAwp9tNLzZA"
          nullable: true
        operationType:
          type: string
          enum: [CREATE, UPDATE, DELETE]
          description: Type of operation being performed
          example: "CREATE"
          nullable: true
        createdTime:
          type: string
          format: date-time
          description: Timestamp when the operation was created
          example: "2025-01-01T01:02:03Z"
          nullable: true
        completedTime:
          type: string
          format: date-time
          description: Timestamp when the operation completed
          example: "2025-01-01T01:05:03Z"
          nullable: true
        error:
          $ref: '#/components/schemas/ErrorResponse'
        _links:
          $ref: '#/components/schemas/OperationLinks'
    OperationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        resource:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href:
          type: string
          description: URL for the link
          example: "https://api.8x8.com/admin-provisioning/operations/op_123456789"
          nullable: true
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 404
          nullable: true
        instance:
          type: string
          description: URI reference that identifies the specific occurrence of the problem
          nullable: true
        time:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: "2025-01-01T01:02:03Z"
          nullable: true
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: "Operation not found"
          nullable: true
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          nullable: true
    Error:
      type: object
      properties:
        field:
          type: string
          description: Field name related to the error
          nullable: true
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Detailed error message
          example: "Operation not found"
          nullable: true
    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