Skip to main content

​
Overview

This page provides a detailed reference for the data structures and schemas used in the Agent Triage Protocol. Understanding these types is essential for implementing both services and clients that interact with the ATP system.

​
Notification Schema

The notification is the core data structure in ATP, encapsulating all information needed for a decision request. 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1.0",
  "timestamp": "2025-05-25T10:30:00Z",
  "deadline": "2025-05-25T11:00:00Z",
  "service": {
    "id": "lovelace-ide",
    "name": "Lovelace IDE",
    "icon": "https://lovelace.dev/icon.png"
  },
  "context": {
    "title": "Deploy to Production?",
    "description": "New version 2.1.0 is ready for deployment to production servers.",
    "project": "backend-api",
    "metadata": {
      "version": "2.1.0",
      "changes": 47,
      "test_coverage": "98.3%"
    },
    "attachments": [
      {
        "type": "text/plain",
        "description": "Release notes",
        "data": "VmVyc2lvbiAyLjEuMCBpbmNsdWRlczoKLSBQZXJmb3JtYW5jZSBpbXByb3ZlbWVudHMKLSBCdWcgZml4ZXMKLSBOZXcgQVBJIGVuZHBvaW50cw=="
      }
    ]
  },
  "actions": [
    {
      "id": "approve",
      "label": "Approve Deployment",
      "response_type": "simple",
      "flags": ["irreversible"]
    },
    {
      "id": "reject",
      "label": "Reject",
      "response_type": "text",
      "constraints": {
        "placeholder": "Reason for rejection"
      }
    }
  ],
  "status": "created"
}

​
Notification Properties

PropertyTypeRequiredDescription
idstring (UUID)YesGlobally unique identifier using UUID v4 format
versionstringYesProtocol version identifier, currently “1.0”
timestampstring (ISO 8601)YesCreation timestamp
deadlinestring (ISO 8601)NoExpiration timestamp
serviceobjectYesService identification object
contextobjectYesContext object containing decision details
actionsarrayYesArray of available action objects
statusstringYesCurrent notification lifecycle state

​
Service Object

PropertyTypeRequiredDescription
idstringYesService identifier assigned during registration
namestringYesHuman-readable service name
iconstring (URL)NoURL pointing to service icon

​
Context Object

PropertyTypeRequiredDescription
titlestringYesConcise summary of the required decision
descriptionstringYesDetailed explanation of the situation
projectstringNoIdentifier for grouping related notifications
metadataobjectNoArbitrary key-value pairs for additional context
attachmentsarrayNoArray of attachment objects

​
Attachment Object

PropertyTypeRequiredDescription
typestring (MIME)YesMIME type of the attachment content
descriptionstringNoHuman-readable description of the attachment
uristring (URL)ConditionalExternal URI reference for the attachment
datastring (Base64)ConditionalBase64-encoded content for inline delivery
Each attachment must include either a uri or data field, but not both.

​
Action Object

PropertyTypeRequiredDescription
idstringYesUnique identifier for the action within this notification
labelstringYesHuman-readable text for UI presentation
response_typestringYesEnumerated type defining expected input format
flagsarray of stringsNoBehavioral characteristics of the action
optionsarray or objectConditionalRequired for choice-based response types
constraintsobjectConditionalRequired for certain response types
Valid response_type values: "simple", "binary", "choice", "multi_choice", "text", "number", "scale" Valid flags values: "destructive", "irreversible", "time_sensitive", "affects_others", "costly", "experimental", "requires_confirmation"

​
Response Schema

The response data structure is used to transmit user decisions back to the originating service. 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "approve",
  "response_data": null,
  "responded_at": "2025-05-25T10:35:12Z",
  "responder": {
    "id": "user_123",
    "type": "human"
  }
}

​
Response Properties

PropertyTypeRequiredDescription
notification_idstring (UUID)YesUUID of the notification being answered
action_idstringYesSelected action identifier from the notification
response_dataanyConditionalUser input data, type determined by action’s response_type
responded_atstring (ISO 8601)YesTimestamp of response submission
responderobjectYesObject containing responder identification

​
Responder Object

PropertyTypeRequiredDescription
idstringYesUnique identifier of responding entity
typestringYesEither “human” or “agent” to indicate responder type

​
Response Data by Type

The format of response_data depends on the action’s response_type:

​
Simple Action

For response_type: "simple", the response_data must be null. 
"response_data": null

​
Binary Choice

For response_type: "binary", the response_data must be a boolean value. 
"response_data": true

​
Single Choice

For response_type: "choice", the response_data must be a string matching one of the option values. 
"response_data": "high"

​
Multiple Choice

For response_type: "multi_choice", the response_data must be an array of strings matching option values. 
"response_data": ["engineering", "security"]

​
Text Input

For response_type: "text", the response_data must be a string. 
"response_data": "The suggestion looks good overall, but we should consider the impact on mobile users."

​
Numeric Input

For response_type: "number", the response_data must be a number. 
"response_data": 0.75

​
Scale/Range

For response_type: "scale", the response_data must be an integer within the defined range. 
"response_data": 4

​
Error Schema

Error responses follow a consistent format across all API endpoints. 
{
  "code": "NOTIFICATION_EXPIRED",
  "message": "The notification deadline has passed and no longer accepts responses",
  "details": {
    "notification_id": "550e8400-e29b-41d4-a716-446655440000",
    "expired_at": "2025-05-25T11:00:00Z"
  },
  "request_id": "req_abc123def456"
}

​
Error Properties

PropertyTypeRequiredDescription
codestringYesStandardized error identifier for programmatic handling
messagestringYesHuman-readable error description
detailsobjectNoAdditional context specific to the error type
request_idstringYesUnique identifier for request tracing

​
Status Update Schema

Status updates are sent via WebSocket or included in REST responses to indicate changes in notification state. 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "invalidated",
  "reason": "The deployment was canceled by the system",
  "timestamp": "2025-05-25T10:32:15Z"
}

​
Status Update Properties

PropertyTypeRequiredDescription
notification_idstring (UUID)YesUUID of the notification being updated
statusstringYesNew notification status
reasonstringNoHuman-readable explanation for status change
timestampstring (ISO 8601)YesTimestamp of the status update

​
WebSocket Message Schema

Messages sent over WebSocket connections follow a consistent envelope format. 
{
  "type": "notification",
  "data": {
    // Notification object
  }
}

​
WebSocket Message Properties

PropertyTypeRequiredDescription
typestringYesMessage type identifier
dataobjectYesMessage payload, structure depends on type
Valid type values: "notification", "status_update", "heartbeat", "error", "acknowledge", "heartbeat_ack"

​
JSON Schema Definitions

For developers who want to implement validation, the complete JSON Schema definitions are available: These schemas can be used with JSON Schema validation libraries to ensure proper format compliance in your implementation.