Current State:

Currently the documentation is missing payload information and information about what can be edited and not:

1. GET Integration Actions Response Differs from Documentation

Endpoint:
GET /v1/integrations/{integrationId}/actions/{id}

Issue:
The response structure is significantly different from what the documentation describes, for a first timer using the API makes it unclear how to interpret the data.
For example:
 
 {{

{ "id": "e62bf78e-01fc-4193-b843-f73dadcfb54b", "type": "postToUrl", "name": "addTags action", "domain": "alert", "direction": "outgoing", "actionMapping": \{ "type": "addTags", "parameter": [ "CreateIncident" ] }

,
"groupType": "forwarding",
"extraField": ""
}}}

 

2. POST Integration Action Documentation Is Vague

Endpoint:
POST /v1/integrations/{integrationId}/actions

Issue:
The documentation states that actionMapping.parameter is an object but does not clarify that it should be a list of key-value pairs. There are no examples for addTags actions. See response GET Integration Actions above, making this even more confusing.

Example of confusion:

• Using the format suggested by GET response:

 
 {{"parameter": [ "CreateIncident"
]}}
Results in:
 
 {{

{ "message": "Internal Server Error", "requestId": "d30fc7d8-9c0d-4e53-8d87-fbda47f9589f" }

}}
Correct format (discovered through trial and error)::
 
 {{"parameter": [ { "value": "CreateIncident" }
]}}
This works and returns 200, but the documentation does not explain this requirement.

3. No Error When Creating Duplicate Actions

Endpoint:
POST /v1/integrations/{integrationId}/actions

Issue:
If an action already exists, creating another with the same name and type returns 200 OK instead of an error or warning. This makes error handling in automation scripts difficult.

Example:

• Existing action: addTags without parameters.

• Send payload with parameters:

 
 {{{ "type": "postToUrl",
"name": "addTags Action",
"domain": "alert",
"direction": "outgoing",
"groupType": "forwarding",
"actionMapping": {
"type": "addTags",
"parameter": [

{ "value": "CreateIncident" }

]
}
}}}
Response:
 
 {{

{ "id": "23fdd0dc-4f8e-4dc6-a4e8-47a67e7fde4d", "type": "postToUrl", "name": "addTags Action", "domain": "alert", "direction": "outgoing", "actionMapping": \{ "type": "addTags", "parameter": [ "CreateIncident" ] }

,
"groupType": "forwarding",
"extraField": ""
}}}
Expected behavior: An error or warning indicating the action already exists.

4. Update Integration Endpoint

Endpoint:
PATCH /v1/integrations/{id}

Problem:
Updating a single property (e.g., enabled or typeSpecificProperties) resets the entire integration configuration. This behavior forces us to:

• Reapply alert filters.

• Recreate all integration actions.

This requires multiple redundant API calls:

• Update integration alert filter.

• List integration actions.

• Delete integration actions.

• Create integration actions.

Expected Behavior:
Partial updates should not affect unrelated properties. Updating the integration properties or enabling/disabling it should not reset filters or actions.

5. Update Integration Actions Endpoint

Endpoint:
PATCH /v1/integrations/{integrationId}/actions/{id}

Problems:

• Documentation does not clearly specify:

• • Which fields can be updated.

• • The expected schema for partial updates.

• Common scenarios fail with INTERNAL_SERVER_ERROR despite valid payloads.

Examples and Errors

Goal: Disable an action.
Payload:
 
 {{

{ "name": "Updated Action Name", "enabled": false }

}}
Error:
 
 {{

{ "message": "Internal Server Error", "took": 0.062, "requestId": "38234100-e095-4d00-97a4-e9d0363452eb" }

}}
Goal: Add tags to an addTags action.

Payload:
 
 {{{ "enabled": true,
"actionMapping": {
"type": "addTags",
"parameter": [

{ "value": "CreateIncident" }

,
{ "value": "Bananas" }
]
}
}}}
Error:
 
 {{

{ "errors": [ \{ "code": "UNPROCESSABLE_ENTITY", "title": "You cannot have two postToUrl actions with the same values" }

]
}}}
Goal: Full payload updates, it’s unclear if this is possible from the documentation.

Payload:
 
 {{{ "name": "Update Tags Action",
"enabled": true,
"filter": {
"conditionMatchType": "match-any-condition",
"conditions": [

{ "field": "tags", "expectedValue": "CreateIncident", "not": false, "operation": "contains", "key": "contains" }

]
},
"typeSpecificProperties": {},
"fieldMappings": {
"tags": []
},
"actionMapping": {
"type": "addTags",
"parameter": [

{ "value": "CreateIncident" }

]
}
}}}
Error: Same as above.
 
 {{

{ "errors": [ \{ "code": "UNPROCESSABLE_ENTITY", "title": "You cannot have two postToUrl actions with the same values" }

]
}}}
 

Proposed Future State:

• True PATCH Semantics:

• • Allow partial updates without resetting unrelated properties.

• Clear Documentation:

• • Specify which fields are updatable for actions.

• • Provide examples for common scenarios (toggle enabled, update actions).

• • Update documentation to clearly define the expected schema for actionMapping.parameter for all action types.

• • Align GET and POST Integration Action response formats or clarify differences.

• Validation & Error Handling

• • Implement validation for duplicate actions or provide a clear warning.

• • Improve error messages for invalid payloads.