Skip to main content

​
Overview

The Agent Triage Protocol provides a comprehensive set of API endpoints to enable communication between AI services, the ATP server, and client applications. This page provides an overview of the available endpoints and their purposes.

​
Base URLs

The API is organized into distinct namespaces:
  • Service API: /api/v1/services/* - Endpoints for AI services to register, send notifications, and manage their notifications
  • Client API: /api/v1/client/* - Endpoints for client applications to retrieve notifications and submit responses
  • Admin API: /api/v1/admin/* - Endpoints for administrative operations (not covered in this documentation)

​
Versioning

All API paths are prefixed with a version identifier (v1 in the current specification). This enables future protocol enhancements without breaking existing implementations. When a new major version is released, both versions will be supported for a designated deprecation period to allow for orderly migration.

​
Rate Limits

To ensure system stability and fair usage, the ATP server implements rate limiting on all API endpoints. Rate limits vary by endpoint type:
  • Service registration: 10 requests per hour per IP address
  • Notification submission: 100 requests per minute per service
  • Notification status updates: 200 requests per minute per service
  • Client notification polling: 60 requests per minute per user
  • Response submission: 100 requests per minute per user
  • WebSocket connections: 5 concurrent connections per user
  • SSE connections: 10 concurrent connections per user
When a rate limit is exceeded, the server responds with HTTP status code 429 Too Many Requests and includes a Retry-After header indicating when the client may resume requests.

​
Service Endpoints

​
Register Service

Service registration establishes the initial trust relationship between an AI service and the ATP server. This operation requires administrative authentication and creates persistent credentials for subsequent service operations. Endpoint: POST /api/v1/services
Authentication: Requires Bearer token with administrative privileges Request Body Schema: 
{
  "name": "Lovelace IDE",
  "description": "AI-powered integrated development environment",
  "callback_url": "https://lovelace.dev/atp/webhook",
  "webhook_secret": "your-secure-random-string"
}
Response Schema: 
{
  "service_id": "lovelace-ide",
  "api_key": "sk_live_lovelace_abc123",
  "webhook_secret": "your-secure-random-string"
}
The service must securely store the returned api_key and service_id for all future interactions with the ATP server.

​
Send Notification

This endpoint enables registered services to submit decision requests for human review. Services must include their API key in the authorization header and provide a complete notification object conforming to the protocol schema. Endpoint: POST /api/v1/notifications
Authentication: Requires Bearer token using service API key Request Body: Complete notification object as defined in the Message Formats section Response Schema: 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "estimated_delivery": "2025-05-25T10:30:05Z"
}
Services should store the notification_id for correlation with subsequent webhook callbacks.

​
Update Notification Status

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. Endpoint: PATCH /api/v1/notifications/{id}
Authentication: Requires Bearer token using service API key Request Body Schema: 
{
  "status": "invalidated",
  "reason": "The issue was automatically resolved by the system"
}
The ATP server will prevent further user responses to invalidated notifications and may notify connected clients of the status change.

​
Client Endpoints

​
Subscribe to Notifications (WebSocket)

The WebSocket endpoint provides real-time notification delivery to connected clients. This connection-oriented approach minimizes latency and enables immediate user awareness of pending decisions. Endpoint: WS /api/v1/client/stream
Authentication: Requires Bearer token using user credentials Upon successful connection, the client receives notification events as they occur. Each event follows a standardized message format: 
{
  "type": "notification",
  "data": {
    // Complete notification object
  }
}
The WebSocket connection automatically handles heartbeat messages to maintain connection health and will attempt reconnection using exponential backoff if the connection is lost.

​
Subscribe to Notifications (Server-Sent Events)

The SSE endpoint provides an alternative method for real-time notification delivery using HTTP-based server-push technology. This approach is beneficial for clients that cannot maintain WebSocket connections due to proxy limitations or require a simpler implementation. Endpoint: GET /api/v1/client/events
Authentication: Requires Bearer token using user credentials Query Parameters:
  • last_event_id (string, optional): ID of the last received event for reconnection purposes
  • types (string, optional): Comma-separated list of event types to subscribe to (default: all)
Upon successful connection, the server keeps the HTTP connection open and sends notification events as they occur. Each event is formatted according to the SSE specification: 
event: notification
id: unique-event-id
data: {"id":"notification-uuid","version":"1.0",...}
The SSE connection supports standard features of the EventSource specification including automatic reconnection with last-event-ID tracking to resume streams after disconnection.

​
Fetch Pending Notifications (REST)

For clients unable to maintain persistent connections, the REST endpoint provides polling-based notification retrieval. This approach supports battery-constrained devices and simplified client implementations. Endpoint: GET /api/v1/client/notifications
Authentication: Requires Bearer token using user credentials Query Parameters:
  • status (string, optional): Filter by notification state, typically “pending”
  • limit (integer, optional): Maximum notifications to return, default 50
  • cursor (string, optional): Pagination cursor from previous response
Response Schema: 
{
  "notifications": [
    // Array of notification objects
  ],
  "pagination": {
    "next_cursor": "cursor_for_next_page",
    "has_more": true
  }
}
The pagination mechanism ensures efficient retrieval of large notification sets while maintaining consistent ordering.

​
Submit Response

This endpoint processes user decisions and forwards them to the originating AI service. The required payload structure varies based on the action’s response_type as defined in the notification. Endpoint: POST /api/v1/client/respond
Authentication: Requires Bearer token using user credentials Request Body Schema: 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "rollback",
  "response_data": null
}
The response_data field must conform to the requirements of the action’s response_type. For details on the format for each response type, see the Response Types documentation.

​
Webhook Callbacks

When a user submits a response, the ATP server delivers it to the originating service via a webhook callback to the URL specified during service registration. HTTP Method: POST
URL: Service’s registered callback URL
Headers:
  • Content-Type: application/json
  • X-ATP-Signature: t=1622145123,v1=5257a869e7ecebb... (HMAC signature for verification)
Callback Body: 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "rollback",
  "response_data": null,
  "responded_at": "2025-05-25T10:35:12Z",
  "responder": {
    "id": "user_123",
    "type": "human"
  }
}
Services must respond with HTTP status 200 to acknowledge successful receipt of the callback. Any other status code will cause the ATP server to retry the delivery with exponential backoff.

​
Error Handling

All API endpoints use standard HTTP status codes and return structured error responses. For details on error handling, see the Error Handling documentation.

​
Implementation Examples

For code examples demonstrating how to use these endpoints in different programming languages, see the Implementation Guides section of the documentation.
⌘I