Workflows API | Keva Docs

The Workflows API allows you to create, retrieve, update, and manage automation workflows that trigger based on events in your support system.

Endpoints

Method	Endpoint	Description
GET	`/api/workflows`	List workflows
POST	`/api/workflows`	Create a workflow
GET	`/api/workflows/:id`	Get workflow details
PATCH	`/api/workflows/:id`	Update a workflow
DELETE	`/api/workflows/:id`	Delete a workflow
POST	`/api/workflows/:id/trigger`	Manually trigger
GET	`/api/workflows/:id/executions`	List executions

List Workflows

Retrieve all workflows for your workspace.

GET /api/workflows

Query Parameters

Parameter	Type	Description
`active`	boolean	Filter by active status only

Example Request

curl "https://app.keva.support/api/workflows?active=true" \
  -H "Authorization: Bearer keva_live_your_api_key"

Example Response

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Auto-assign VIP tickets",
      "description": "Route VIP customer tickets to senior agents",
      "isActive": true,
      "triggerType": "ticket_created",
      "version": 3,
      "executionCount": 156,
      "lastTriggeredAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-01T10:00:00Z",
      "updatedAt": "2024-01-10T12:00:00Z"
    }
  ]
}

Create Workflow

Create a new automation workflow.

POST /api/workflows

Request Body

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	No	Description
`triggerType`	string	No	Trigger type (default: `ticket_created`)
`workflowJson`	object	No	Workflow graph definition

Trigger Types

Type	Description
`ticket_created`	When a new ticket is created
`ticket_updated`	When a ticket is updated
`ticket_closed`	When a ticket is closed
`message_received`	When a message is received
`tag_added`	When a tag is added to a ticket
`manual`	Manually triggered only
`scheduled`	Runs on a schedule
`webhook`	Triggered by external webhook

Example Request

curl -X POST https://app.keva.support/api/workflows \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Escalate urgent tickets",
    "description": "Notify team lead when urgent ticket is created",
    "triggerType": "ticket_created"
  }'

Example Response

{
  "workflow": {
    "id": "wf_new789",
    "name": "Escalate urgent tickets",
    "description": "Notify team lead when urgent ticket is created",
    "triggerType": "ticket_created",
    "isActive": false,
    "version": 1,
    "createdAt": "2024-01-15T18:00:00Z"
  }
}

Get Workflow

Retrieve a workflow with its full configuration.

GET /api/workflows/:id

Example Response

{
  "workflow": {
    "id": "wf_abc123",
    "name": "Auto-assign VIP tickets",
    "triggerType": "ticket_created",
    "isActive": true,
    "workflowJson": {
      "nodes": [
        {
          "id": "trigger_1",
          "type": "trigger",
          "data": { "triggerType": "ticket_created" }
        },
        {
          "id": "condition_1",
          "type": "condition",
          "data": {
            "field": "customer.isVip",
            "operator": "equals",
            "value": true
          }
        },
        {
          "id": "action_1",
          "type": "action",
          "data": {
            "actionType": "assign_ticket",
            "assignTo": "user_senior123"
          }
        }
      ],
      "edges": [
        { "source": "trigger_1", "target": "condition_1" },
        { "source": "condition_1", "target": "action_1", "label": "true" }
      ]
    }
  }
}

Update Workflow

Update workflow properties or configuration.

PATCH /api/workflows/:id

Request Body

Field	Type	Description
`name`	string	New name
`description`	string	New description
`isActive`	boolean	Enable/disable workflow
`workflowJson`	object	Updated workflow graph

Example: Activate Workflow

curl -X PATCH https://app.keva.support/api/workflows/wf_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"isActive": true}'

Delete Workflow

Delete a workflow (cannot be undone).

DELETE /api/workflows/:id

Example Request

curl -X DELETE https://app.keva.support/api/workflows/wf_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key"

Manual Trigger

Trigger a workflow manually with custom data.

POST /api/workflows/:id/trigger

Request Body

Field	Type	Description
`ticketId`	string	Ticket to run workflow on
`data`	object	Custom data for the execution

Example Request

curl -X POST https://app.keva.support/api/workflows/wf_abc123/trigger \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"ticketId": "tkt_xyz789"}'

List Executions

Get execution history for a workflow.

GET /api/workflows/:id/executions

Example Response

{
  "executions": [
    {
      "id": "exec_001",
      "workflowId": "wf_abc123",
      "status": "completed",
      "triggeredBy": "ticket_created",
      "ticketId": "tkt_xyz789",
      "startedAt": "2024-01-15T14:30:00Z",
      "completedAt": "2024-01-15T14:30:02Z",
      "steps": [
        { "nodeId": "condition_1", "status": "passed", "result": true },
        { "nodeId": "action_1", "status": "completed" }
      ]
    }
  ]
}

Execution Statuses

Status	Description
`pending`	Queued for execution
`running`	Currently executing
`completed`	Finished successfully
`failed`	Execution failed
`cancelled`	Manually cancelled