Documentation Index
Fetch the complete documentation index at: https://atp.hypertext.studio/llms.txt
Use this file to discover all available pages before exploring further.
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
| Parameter | Type | Description |
|---|
id | string | The UUID of the notification to update |
Request Body
{
"status": "invalidated",
"reason": "The issue was automatically resolved by the system"
}
| Field | Type | Required | Description |
|---|
status | string | Yes | New status value, typically “invalidated” |
reason | string | No | Human-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"
}
| Field | Type | Description |
|---|
notification_id | string | UUID of the updated notification |
status | string | New status of the notification |
updated_at | datetime | Timestamp of the status update |
Error Responses
| Status Code | Error Code | Description |
|---|
400 Bad Request | INVALID_STATUS | Requested status is not valid |
401 Unauthorized | AUTH_INVALID_TOKEN | Service API key is invalid |
403 Forbidden | SERVICE_NOT_OWNER | Service does not own this notification |
404 Not Found | NOTIFICATION_NOT_FOUND | Notification with specified ID does not exist |
409 Conflict | NOTIFICATION_ALREADY_RESPONDED | Notification 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:
- Automated Resolution: The issue that prompted the notification was resolved automatically by the system
- State Change: The underlying state has changed, making the decision request obsolete
- Error Correction: The notification was sent with incorrect information
- Decision Made Elsewhere: The decision was made through an alternative channel
- 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
