8x8 Administration - Operations API
8x8 Administration Operations API for tracking the status of long-running provisioning operations.
OpenAPI Specification
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