Skip to main content

​
Overview

Services may invalidate notifications that are no longer relevant due to state changes or automated resolution. This prevents users from responding to outdated decision requests.

​
Request

Endpoint: PATCH /api/v1/notifications/{id}
Authentication: Requires Bearer token using service API key

​
Path Parameters

ParameterTypeDescription
idstringThe UUID of the notification to update

​
Request Body

{
  "status": "invalidated",
  "reason": "The issue was automatically resolved by the system"
}
FieldTypeRequiredDescription
statusstringYesNew status value, typically “invalidated”
reasonstringNoHuman-readable explanation for status change

​
Response

​
Success Response

Status Code: 200 OK 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "invalidated",
  "updated_at": "2025-05-25T10:35:12Z"
}
FieldTypeDescription
notification_idstringUUID of the updated notification
statusstringNew status of the notification
updated_atdatetimeTimestamp of the status update
The ATP server will prevent further user responses to invalidated notifications and may notify connected clients of the status change.

​
Error Responses

Status CodeError CodeDescription
400 Bad RequestINVALID_STATUSRequested status is not valid
401 UnauthorizedAUTH_INVALID_TOKENService API key is invalid
403 ForbiddenSERVICE_NOT_OWNERService does not own this notification
404 Not FoundNOTIFICATION_NOT_FOUNDNotification with specified ID does not exist
409 ConflictNOTIFICATION_ALREADY_RESPONDEDNotification has already been responded to

​
Status Transitions

Notifications can only transition to terminal states:
  • From created to invalidated
  • From delivered to invalidated
  • From acknowledged to invalidated
Once a notification is in responded, completed, expired, or invalidated state, no further status updates are allowed.

​
Examples

​
cURL Example

curl -X PATCH "https://atp.example.com/api/v1/notifications/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_lovelace_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "invalidated",
    "reason": "The issue was automatically resolved by the system"
  }'

​
Python Example

from atp import ATPClient

# Initialize the ATP client with service credentials
client = ATPClient(api_key="sk_live_lovelace_abc123")

# Invalidate a notification that's no longer relevant
result = client.invalidate_notification(
    notification_id="550e8400-e29b-41d4-a716-446655440000",
    reason="The issue was automatically resolved by the system"
)

print(f"Notification status updated to: {result.status}")

​
Use Cases

Common scenarios for invalidating notifications include:
  1. Automated Resolution: The issue that prompted the notification was resolved automatically by the system
  2. State Change: The underlying state has changed, making the decision request obsolete
  3. Error Correction: The notification was sent with incorrect information
  4. Decision Made Elsewhere: The decision was made through an alternative channel
  5. Service Shutdown: The service is shutting down and wants to clean up pending notifications

​
Best Practices

  • Always provide a clear reason when invalidating notifications
  • Invalidate notifications as soon as they’re no longer relevant
  • Consider sending a replacement notification if the decision is still needed but in a modified form
  • Implement webhook handlers for status update events to keep your system in sync
⌘I