Overview

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.

Request

Endpoint: POST /api/v1/client/respond
Authentication: Requires Bearer token using user credentials

Request Body

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "approve",
  "response_data": null
}

Field	Type	Required	Description
`notification_id`	string	Yes	UUID of the notification being answered
`action_id`	string	Yes	Selected action identifier from the notification
`response_data`	any	Conditional	Required for all response types except `"simple"`

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.

Response

Success Response

Status Code: 200 OK

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "approve",
  "status": "responded",
  "responded_at": "2025-05-25T10:35:12Z"
}

Field	Type	Description
`notification_id`	string	UUID of the notification that was answered
`action_id`	string	Identifier of the selected action
`status`	string	Updated notification status, typically “responded”
`responded_at`	datetime	Timestamp when the response was recorded

Error Responses

Status Code	Error Code	Description
`400 Bad Request`	`MISSING_REQUIRED_FIELD`	Required field is missing from request
`400 Bad Request`	`INVALID_ACTION_ID`	The specified action_id doesn’t exist for this notification
`400 Bad Request`	`INVALID_RESPONSE_DATA`	Response data doesn’t match expected format
`401 Unauthorized`	`AUTH_INVALID_TOKEN`	User token is invalid
`403 Forbidden`	`NOTIFICATION_ACCESS_DENIED`	User does not have access to this notification
`404 Not Found`	`NOTIFICATION_NOT_FOUND`	Notification with specified ID does not exist
`409 Conflict`	`NOTIFICATION_EXPIRED`	Notification deadline has passed
`409 Conflict`	`NOTIFICATION_INVALIDATED`	Service marked notification as invalid
`409 Conflict`	`NOTIFICATION_ALREADY_RESPONDED`	Notification has already been answered
`422 Unprocessable Entity`	`CONSTRAINT_VIOLATION`	Response violates defined constraints

Response Type Examples

Here are examples of valid request bodies for each response type:

Simple Action

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "approve",
  "response_data": null
}

Binary Choice

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "include_logs",
  "response_data": true
}

Single Choice

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "select_action",
  "response_data": "option1"
}

Multiple Choice

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "select_recipients",
  "response_data": ["engineering", "security"]
}

Text Input

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "feedback",
  "response_data": "The suggestion looks good overall, but we should consider the impact on mobile users."
}

Numeric Input

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "set_threshold",
  "response_data": 0.75
}

Scale/Range

{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_id": "confidence_rating",
  "response_data": 4
}

Examples

JavaScript Example

async function submitResponse(notificationId, actionId, responseData) {
  try {
    const response = await fetch(
      'https://atp.example.com/api/v1/client/respond',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer user_token_xyz789',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          notification_id: notificationId,
          action_id: actionId,
          response_data: responseData
        })
      }
    );
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error ${response.status}: ${errorData.message}`);
    }
    
    const data = await response.json();
    console.log(`Response submitted successfully: ${data.status}`);
    
    return data;
  } catch (error) {
    console.error('Error submitting response:', error);
    throw error;
  }
}

// Usage examples for different response types
submitResponse('550e8400-e29b-41d4-a716-446655440000', 'approve', null);
submitResponse('550e8400-e29b-41d4-a716-446655440000', 'include_logs', true);
submitResponse('550e8400-e29b-41d4-a716-446655440000', 'select_action', 'option1');
submitResponse('550e8400-e29b-41d4-a716-446655440000', 'feedback', 'Looks good!');

Python Example

import requests

def submit_response(token, notification_id, action_id, response_data=None):
    url = 'https://atp.example.com/api/v1/client/respond'
    
    payload = {
        'notification_id': notification_id,
        'action_id': action_id
    }
    
    # Only include response_data if it's not None
    if response_data is not None:
        payload['response_data'] = response_data
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        print(f"Response submitted successfully: {data['status']}")
        
        return data
    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        print(f"Error {e.response.status_code}: {error_data['message']}")
        raise

# Usage examples for different response types
submit_response('user_token_xyz789', '550e8400-e29b-41d4-a716-446655440000', 'approve')
submit_response('user_token_xyz789', '550e8400-e29b-41d4-a716-446655440000', 'include_logs', True)
submit_response('user_token_xyz789', '550e8400-e29b-41d4-a716-446655440000', 'select_action', 'option1')
submit_response('user_token_xyz789', '550e8400-e29b-41d4-a716-446655440000', 'feedback', 'Looks good!')

Error Handling

When submitting responses, it’s important to handle errors gracefully. Here’s a more comprehensive error handling approach:

async function submitResponseWithRetry(notificationId, actionId, responseData) {
  const MAX_RETRIES = 3;
  let attempt = 0;
  
  while (attempt <= MAX_RETRIES) {
    try {
      const response = await fetch(
        'https://atp.example.com/api/v1/client/respond',
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer user_token_xyz789',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            notification_id: notificationId,
            action_id: actionId,
            response_data: responseData
          })
        }
      );
      
      if (response.ok) {
        return await response.json();
      }
      
      const errorData = await response.json();
      
      // Handle specific error cases
      switch (errorData.code) {
        case 'NOTIFICATION_EXPIRED':
        case 'NOTIFICATION_INVALIDATED':
        case 'NOTIFICATION_ALREADY_RESPONDED':
          // Terminal state, don't retry
          throw new Error(`${errorData.code}: ${errorData.message}`);
          
        case 'INVALID_RESPONSE_DATA':
        case 'CONSTRAINT_VIOLATION':
          // Client error, don't retry
          throw new Error(`${errorData.code}: ${errorData.message}`);
          
        case 'RATE_LIMIT_EXCEEDED':
          // Rate limiting, retry with backoff
          const retryAfter = response.headers.get('Retry-After');
          const delayMs = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
          await new Promise(resolve => setTimeout(resolve, delayMs));
          attempt++;
          continue;
      }
      
      // Server errors (5xx) are retryable
      if (response.status >= 500) {
        const delayMs = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delayMs));
        attempt++;
        continue;
      }
      
      // Other errors are considered permanent
      throw new Error(`${errorData.code}: ${errorData.message}`);
      
    } catch (error) {
      // Network errors are retryable
      if (error.name === 'TypeError' && attempt < MAX_RETRIES) {
        const delayMs = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delayMs));
        attempt++;
        continue;
      }
      throw error;
    }
  }
  
  // If we've exhausted retries
  throw new Error('Maximum retry attempts reached');
}

Best Practices

Validate Response Data: Verify that response data matches the expected format before submitting
Handle Terminal States: Gracefully handle expired or invalidated notifications
Implement Retries: Use exponential backoff for retrying transient failures
Offline Support: Queue responses locally when offline and submit when connectivity is restored
User Feedback: Provide immediate feedback to users while the response is being processed
Security: Never log or expose sensitive response data

Overview

Services

Clients

Submit Response

Overview

Request

Request Body

Response

Success Response

Error Responses

Response Type Examples

Simple Action

Binary Choice

Single Choice

Multiple Choice

Text Input

Numeric Input

Scale/Range

Examples

JavaScript Example

Python Example

Error Handling

Best Practices

Overview

Services

Clients

​Overview

​Request

​Request Body

​Response

​Success Response

​Error Responses

​Response Type Examples

​Simple Action

​Binary Choice

​Single Choice

​Multiple Choice

​Text Input

​Numeric Input

​Scale/Range

​Examples

​JavaScript Example

​Python Example

​Error Handling

​Best Practices

Overview

Request

Request Body

Response

Success Response

Error Responses

Response Type Examples

Simple Action

Binary Choice

Single Choice

Multiple Choice

Text Input

Numeric Input

Scale/Range

Examples

JavaScript Example

Python Example

Error Handling

Best Practices