Automation API
8x8 Automation API for defining, launching and managing communication workflow definitions and workflow instances across channels.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Automation API",
"version": "1.0",
"description": "API for managing workflows on 8x8 Automation",
"contact": {
"name": "8x8 Inc",
"url": "https://cpaas.8x8.com",
"email": "cpaas-support@8x8.com"
},
"termsOfService": "https://cpaas.8x8.com/sg/terms-and-conditions/"
},
"servers": [
{
"url": "https://automation.8x8.com"
}
],
"paths": {
"/api/v1/accounts/{accountId}/definitions": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"get": {
"operationId": "get-all-definitions",
"tags": ["Workflow Definition Management"],
"summary": "Retrieve a list of active workflow definitions.",
"description": "Use this resource to explore currently active definitions. Workflows are started based on these definitions when the trigger conditions are met. Use the parameters `limit` and `offset` to paginate through the definitions list.",
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
}
],
"responses": {
"200": {
"description": "List of workflow definitions",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/definition"
}
},
"examples": {
"definition": {
"$ref": "#/components/examples/definitions"
}
}
}
}
}
}
},
"post": {
"operationId": "create-definition",
"tags": ["Workflow Definition Management"],
"summary": "Create a new workflow definition",
"description": "Use this resource to create and activate a new workflow definition.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/definitionInput"
},
"examples": {
"definitionInput": {
"$ref": "#/components/examples/definitionInput"
}
}
}
}
},
"responses": {
"201": {
"description": "Newly created workflow definition.",
"headers": {
"Location": {
"schema": {
"type": "string"
},
"description": "Path to the newly created workflow definition"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/definition"
},
"examples": {
"definitionInput": {
"$ref": "#/components/examples/definition"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionError"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/definitions/{definitionId}": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"$ref": "#/components/parameters/definitionId"
}
],
"get": {
"operationId": "get-specific-definition",
"tags": ["Workflow Definition Management"],
"summary": "Retrieve the version history of a workflow definition.",
"description": "Use this resource to explore different versions of a workflow definition. Results are ordered in the descending order of the version.",
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
}
],
"responses": {
"200": {
"description": "List of definitions. If there are no definitions by the specified definition id, an empty list is returned.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/definition"
}
},
"examples": {
"definition": {
"$ref": "#/components/examples/definitionVersions"
}
}
}
}
},
"400": {
"description": "Definition id is invalid (not a valid uuid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
}
}
},
"put": {
"operationId": "update-existing-definition",
"tags": ["Workflow Definition Management"],
"summary": "Update workflow definition",
"description": "Use this resource to update an existing workflow definition. Updating a workflow definition creates and registers a new version of the definition and preserves the old definition in version history. This ensures that any workflows that have already been started from the old version runs to completion while new workflows are started based on the latest version of the workflow definition.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/definitionInput"
},
"examples": {
"definitionInput": {
"$ref": "#/components/examples/definitionInput"
}
}
}
}
},
"responses": {
"200": {
"description": "Updated workflow definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/definition"
},
"examples": {
"definitionInput": {
"$ref": "#/components/examples/definition"
}
}
}
}
},
"400": {
"description": "Request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionError"
}
}
}
}
},
"404": {
"description": "Workflow definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
},
"delete": {
"operationId": "delete-definitions",
"tags": ["Workflow Definition Management"],
"summary": "Delete workflow definition",
"description": "Use this resource to delete workflow definitions. Specify the version of the definition to delete in the query parameter. If no version is specified, all versions of the definition will be deleted. Deleting a definition cancels any active event subscriptions, terminates all active workflows, and deletes workflow execution logs that are based on the definition that is being deleted. Once a workflow is deleted, there is no way to reverse the operation.",
"parameters": [
{
"$ref": "#/components/parameters/version"
}
],
"responses": {
"202": {
"description": "Response indicating that a task has been scheduled to delete the workflow definition."
},
"400": {
"description": "Definition id is invalid (not a valid uuid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/definitions/{definitionId}/workflows": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"$ref": "#/components/parameters/definitionId"
}
],
"get": {
"operationId": "get-workflow-instances",
"tags": ["Workflow Instance Management"],
"summary": "Retrieve a list of workflow instances",
"description": "Use this resource to explore workflows created based on a specific workflow definition. If the definition version is not specified, workflows for the latest version are returned. Results are ordered in descending order of their creation time. Use parameters `limit` and `offset` to paginate through the list.",
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/version"
},
{
"schema": {
"type": "string",
"enum": ["Runnable", "Suspended", "Complete", "Terminated"],
"description": "Workflow instance status. Supported statuses are\n * Runnable (workflows that are in progress)\n * Complete (workflows that have completed without errors)\n * Suspended (workflows that have been suspended)\n * Terminated (workflows that have been manually terminated or faulted)"
},
"in": "query",
"name": "status"
},
{
"schema": {
"type": "string",
"example": "2021-06-24T09:33:06.60Z"
},
"in": "query",
"name": "startTimeFrom",
"description": "Minimum workflow instance start time in ISO 8601 format"
},
{
"schema": {
"type": "string",
"example": "2021-06-24T09:33:06.60Z"
},
"in": "query",
"name": "startTimeTo",
"description": "Maximum workflow instance start time in ISO 8601 format"
}
],
"responses": {
"200": {
"description": "List of workflow instances. If there are no workflows by the specified definition id, an empty list is returned.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflowInstance"
}
},
"examples": {
"workflowInstances": {
"$ref": "#/components/examples/workflowInstances"
}
}
}
}
},
"400": {
"description": "Definition id is invalid (not a valid uuid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
},
"post": {
"operationId": "start-workflow-instance",
"tags": ["Workflow Definition Management"],
"summary": "Test workflow definition",
"description": "Use this resource to test workflow definition by starting workflow instances. This endpoint is useful for testing your workflows without involving external triggers like inbound messages.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 1
},
"in": "query",
"name": "version",
"description": "Version of the definition to test. If not specified, latest version is used."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Workflow data required by the workflow. For instance, if you are trying to test a workflow that is supposed to be started by an inbound chat apps message, the request data should simulate an actual inbound webhook call. If you are unsure what the webhook payload is like for your account, please refer to [webhook object structure](/connect/reference#webhook-object-structure) or contact support."
},
"example": {
"namespace": "ChatApps",
"eventType": "inbound_message_received",
"description": "ChatApps inbound message",
"payload": {
"umid": "9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
"subAccountId": "test_subaccount_id",
"timestamp": "2016-01-01T14:34:56.017Z",
"user": {
"msisdn": "xxxxxxxxxx",
"channelUserId": "test_user_id",
"name": "test_user"
},
"recipient": {
"channel": "whatsapp",
"channelId": "269a57f4-3522-eb11-8278-00155d9f27ac"
},
"type": "text",
"content": {
"text": "Welcome to 8x8 Automation!"
}
}
}
}
}
},
"responses": {
"201": {
"description": "A new workflow instance has been started from the specified workflow.",
"headers": {
"Location": {
"schema": {
"type": "string"
},
"description": "Path to the newly started workflow instance."
}
}
},
"400": {
"description": "Definition id is invalid (not a valid uuid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/definitions/{definitionId}/workflows/{workflowId}": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"$ref": "#/components/parameters/definitionId"
},
{
"$ref": "#/components/parameters/workflowId"
}
],
"get": {
"operationId": "get-instance-status",
"tags": ["Workflow Instance Management"],
"summary": "Retrieve workflow instance status",
"description": "Use this resource to view the status of a workflow instance.",
"parameters": [
{
"schema": {
"type": "boolean",
"default": false,
"example": true
},
"in": "query",
"name": "includeLogs",
"description": "If set to true, response includes detailed execution logs of workflow steps. This information is useful when debugging a workflow definition."
}
],
"responses": {
"200": {
"description": "Workflow instance.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/workflowInstance"
},
{
"$ref": "#/components/schemas/workflowInstanceWithLogs"
}
]
},
"examples": {
"workflow instance": {
"$ref": "#/components/examples/workflowInstance"
},
"workflow instance with logs": {
"$ref": "#/components/examples/workflowInstanceWithLogs"
}
}
}
}
},
"400": {
"description": "Workflow definition id or the workflow instance id is invalid (not a valid uuid).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow instance or definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
},
"patch": {
"operationId": "patch-workflow-instance",
"tags": ["Workflow Instance Management"],
"summary": "Update workflow instance status",
"description": "Use this resource to control the state of a workflow instance. For example, you can suspend a workflow to be resumed later or terminate a workflow due to an error.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["suspend", "resume", "terminate"],
"description": "List of commands available. Supported commands are\n * suspend (suspends a workflow that is currently in progress)\n * resume (resumes a currently suspended workflow)\n * terminate (terminates the workflow. A terminated workflow cannot be resumed)"
}
}
},
"example": {
"status": "suspend"
}
}
}
},
"responses": {
"200": {
"description": "Workflow status successfully updated."
},
"400": {
"description": "Request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow instance or definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/definitions/{definitionId}/workflows/{workflowId}/errors": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"$ref": "#/components/parameters/definitionId"
},
{
"$ref": "#/components/parameters/workflowId"
}
],
"get": {
"operationId": "get-instance-errors",
"tags": ["Workflow Instance Management"],
"summary": "Retrieve a list of errors for a workflow instance",
"description": "Use this resource to retrieve a list of runtime errors for a workflow instance. If the workflow definition is not working as expected, workflow errors help you figure out what went wrong.",
"responses": {
"200": {
"description": "List of workflow instance errors.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/workflowErrors"
}
},
"examples": {
"workflowError": {
"$ref": "#/components/examples/workflowError"
}
}
}
}
},
"400": {
"description": "Request is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/invalidDefinitionIdError"
}
}
}
}
},
"404": {
"description": "Workflow instance or definition is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
},
"examples": {
"error": {
"$ref": "#/components/examples/definitionNotFoundError"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/triggers/http_request": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"schema": {
"type": "string",
"example": "test_subaccount_id"
},
"in": "query",
"name": "subAccountId",
"description": "Subaccount id to trigger definitions that must be run only for specific subaccounts."
}
],
"post": {
"operationId": "http_request_trigger",
"tags": ["Workflow Triggers"],
"summary": "Trigger workflows using an external event",
"description": "Use this resource to trigger workflows from an external system. Inbound SMS and chat apps message triggers are managed by the automation service. However, if you would like to trigger workflows from an external system like your CRM or ERP application or even a 3rd party system, you can use the `http_request` trigger to do so.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Workflow data. Request body can be any JSON containing data required by your workflow. This data will be saved to the workflow context when a workflow is triggered. You can access that data from the workflow using the `data`."
},
"example": {
"customer_id": "customer id",
"user": {
"user_id": "user id",
"contact": "contact number",
"email": "user@example.com"
},
"event": "new sign up"
}
}
}
},
"responses": {
"200": {
"description": "An event to trigger workflows is successfully raised."
}
}
}
},
"/api/v1/accounts/{accountId}/steps/timezones": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"get": {
"operationId": "get-timezones",
"tags": ["Miscellaneous"],
"summary": "Retrieve a list of supported time zones",
"description": "Use this resource to explore supported time zones. Time zones are used as parameters in some of our time related JavaScript helper functions like `IsTimeOfDayBetween(time, start, end, timeZone)`.",
"parameters": [
{
"schema": {
"type": "string",
"example": "europe"
},
"in": "query",
"name": "contains",
"description": "Filter time zones by name. For instance, setting the `contains` to \"europe\" lists all time zones with names that contain the string \"europe\" (case insensitive match)."
}
],
"responses": {
"200": {
"description": "List of time zones.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/timezone"
}
},
"examples": {
"timezones": {
"$ref": "#/components/examples/timezones"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/steps/functions": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"get": {
"operationId": "get-functions",
"tags": ["Miscellaneous"],
"summary": "Retrieve a list of supported JavaScript functions",
"description": "Automation supports scripting in inputs, outputs and select next steps using JavaScript (supports most features of ECMAScript 2023). On top of standard functions, we have added some custom functions to make scripting easier for you. Use this resource to explore our custom functions.",
"responses": {
"200": {
"description": "List of supported functions.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/function"
}
},
"examples": {
"timezones": {
"$ref": "#/components/examples/functions"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/usage": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"get": {
"operationId": "get-usage",
"tags": ["Miscellaneous"],
"summary": "Retrieve the allowed workflow counts and current usage",
"description": "API which can be used to fetch usage and billing-related information for Automation service",
"responses": {
"200": {
"description": "List of supported functions.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/usage"
}
},
"examples": {
"usage": {
"$ref": "#/components/examples/usageResults"
}
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/usage/history": {
"parameters": [
{
"$ref": "#/components/parameters/accountId"
}
],
"get": {
"operationId": "get-usage-history",
"tags": ["Miscellaneous"],
"summary": "Retrieve a list of executed workflow counts by yearly",
"description": "API which can be used to fetch usage historical data for Automation service",
"responses": {
"200": {
"description": "List of supported functions.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/usageHistory"
}
},
"examples": {
"usages": {
"$ref": "#/components/examples/usageHistoryResults"
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"accountId": {
"name": "accountId",
"in": "path",
"description": "Account id",
"required": true,
"schema": {
"type": "string",
"example": "test_account_id"
}
},
"definitionId": {
"name": "definitionId",
"in": "path",
"description": "Workflow definition id.",
"required": true,
"schema": {
"type": "string",
"example": "5870442f-3ddd-4657-b74c-6e17308f5230"
}
},
"workflowId": {
"name": "workflowId",
"in": "path",
"description": "Workflow instance id.",
"required": true,
"schema": {
"type": "string",
"example": "60dbe307fe55d99fc083db61"
}
},
"limit": {
"name": "limit",
"in": "query",
"description": "Number of items to include in the response.",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
}
},
"offset": {
"name": "offset",
"in": "query",
"description": "Page offset. Setting limit to 10 and offset to 0 returns the first 10 items. Increment offset to retrieve more items.",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-connect-automation-api.json