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

Property	Type	Required	Description
`id`	string (UUID)	Yes	Globally unique identifier using UUID v4 format
`version`	string	Yes	Protocol version identifier, currently “1.0”
`timestamp`	string (ISO 8601)	Yes	Creation timestamp
`deadline`	string (ISO 8601)	No	Expiration timestamp
`service`	object	Yes	Service identification object
`context`	object	Yes	Context object containing decision details
`actions`	array	Yes	Array of available action objects
`status`	string	Yes	Current notification lifecycle state

Service Object

Property	Type	Required	Description
`id`	string	Yes	Service identifier assigned during registration
`name`	string	Yes	Human-readable service name
`icon`	string (URL)	No	URL pointing to service icon

Context Object

Property	Type	Required	Description
`title`	string	Yes	Concise summary of the required decision
`description`	string	Yes	Detailed explanation of the situation
`project`	string	No	Identifier for grouping related notifications
`metadata`	object	No	Arbitrary key-value pairs for additional context
`attachments`	array	No	Array of attachment objects

Attachment Object

Property	Type	Required	Description
`type`	string (MIME)	Yes	MIME type of the attachment content
`description`	string	No	Human-readable description of the attachment
`uri`	string (URL)	Conditional	External URI reference for the attachment
`data`	string (Base64)	Conditional	Base64-encoded content for inline delivery

Each attachment must include either a uri or data field, but not both.

Action Object

Property	Type	Required	Description
`id`	string	Yes	Unique identifier for the action within this notification
`label`	string	Yes	Human-readable text for UI presentation
`response_type`	string	Yes	Enumerated type defining expected input format
`flags`	array of strings	No	Behavioral characteristics of the action
`options`	array or object	Conditional	Required for choice-based response types
`constraints`	object	Conditional	Required 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

Property	Type	Required	Description
`notification_id`	string (UUID)	Yes	UUID of the notification being answered
`action_id`	string	Yes	Selected action identifier from the notification
`response_data`	any	Conditional	User input data, type determined by action’s response_type
`responded_at`	string (ISO 8601)	Yes	Timestamp of response submission
`responder`	object	Yes	Object containing responder identification

Responder Object

Property	Type	Required	Description
`id`	string	Yes	Unique identifier of responding entity
`type`	string	Yes	Either “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

Property	Type	Required	Description
`code`	string	Yes	Standardized error identifier for programmatic handling
`message`	string	Yes	Human-readable error description
`details`	object	No	Additional context specific to the error type
`request_id`	string	Yes	Unique 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

Property	Type	Required	Description
`notification_id`	string (UUID)	Yes	UUID of the notification being updated
`status`	string	Yes	New notification status
`reason`	string	No	Human-readable explanation for status change
`timestamp`	string (ISO 8601)	Yes	Timestamp 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

Property	Type	Required	Description
`type`	string	Yes	Message type identifier
`data`	object	Yes	Message 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.

Documentation Index

​Overview

​Notification Schema

​Notification Properties

​Service Object

​Context Object

​Attachment Object

​Action Object

​Response Schema

​Response Properties

​Responder Object

​Response Data by Type

​Simple Action

​Binary Choice

​Single Choice

​Multiple Choice

​Text Input

​Numeric Input

​Scale/Range

​Error Schema

​Error Properties

​Status Update Schema

​Status Update Properties

​WebSocket Message Schema

​WebSocket Message Properties

​JSON Schema Definitions