Skip to main content

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

This endpoint enables registered services to submit decision requests for human review. The notification can include various types of actions that request different forms of user input.

​
Request

Endpoint: POST /api/v1/notifications
Authentication: Requires Bearer token using service API key

​
Request Body

The request body should contain a complete notification object as defined in the Message Formats section. Here’s a simplified example: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1.0",
  "timestamp": "2025-05-25T10:30:00Z",
  "deadline": "2025-05-25T11:00:00Z",
  "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"
      }
    },
    {
      "id": "delay",
      "label": "Delay Deployment",
      "response_type": "choice",
      "options": [
        {"value": "1h", "label": "1 hour"},
        {"value": "4h", "label": "4 hours"},
        {"value": "1d", "label": "1 day"}
      ]
    }
  ]
}

​
Response

​
Success Response

Status Code: 201 Created 
{
  "notification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "estimated_delivery": "2025-05-25T10:30:05Z"
}
FieldTypeDescription
notification_idstringUnique identifier for tracking the notification
statusstringCurrent notification state, initially “created”
estimated_deliverydatetimeProjected delivery timestamp in ISO 8601 format
Services should store the notification_id for correlation with subsequent webhook callbacks.

​
Error Responses

Status CodeError CodeDescription
400 Bad RequestMISSING_REQUIRED_FIELDRequired field is missing from request
400 Bad RequestINVALID_RESPONSE_TYPEUnknown response type specified
400 Bad RequestMALFORMED_ACTIONAction definition is incomplete or invalid
401 UnauthorizedAUTH_INVALID_TOKENService API key is invalid
403 ForbiddenSERVICE_SUSPENDEDService has been temporarily suspended
422 Unprocessable EntityCONSTRAINT_VIOLATIONRequest violates defined constraints
429 Too Many RequestsRATE_LIMIT_EXCEEDEDRate limit for notification creation exceeded

​
Examples

​
cURL Example

curl -X POST "https://atp.example.com/api/v1/notifications" \
  -H "Authorization: Bearer sk_live_lovelace_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "version": "1.0",
    "timestamp": "2025-05-25T10:30:00Z",
    "deadline": "2025-05-25T11:00:00Z",
    "context": {
      "title": "Deploy to Production?",
      "description": "New version 2.1.0 is ready for deployment to production servers.",
      "project": "backend-api"
    },
    "actions": [
      {
        "id": "approve",
        "label": "Approve Deployment",
        "response_type": "simple",
        "flags": ["irreversible"]
      },
      {
        "id": "reject",
        "label": "Reject",
        "response_type": "text",
        "constraints": {
          "placeholder": "Reason for rejection"
        }
      }
    ]
  }'

​
Python Example

from atp import ATPClient, TriageNotification, Action, ResponseType
from datetime import datetime, timedelta

# Initialize the ATP client with service credentials
client = ATPClient(api_key="sk_live_lovelace_abc123")

# Create a notification for a deployment decision
notification = TriageNotification(
    title="Deploy to Production?",
    description="New version 2.1.0 is ready for deployment to production servers.",
    project="backend-api",
    actions=[
        Action(
            id="approve",
            label="Approve Deployment",
            response_type=ResponseType.SIMPLE,
            flags=["irreversible"]
        ),
        Action(
            id="reject",
            label="Reject",
            response_type=ResponseType.TEXT,
            constraints={"placeholder": "Reason for rejection"}
        )
    ],
    deadline=datetime.now() + timedelta(hours=4)
)

# Send the notification
response = client.send_notification(notification)
print(f"Notification sent: {response.notification_id}")

​
Best Practices

  • Always include a descriptive title and detailed description
  • Set appropriate deadlines based on the urgency of the decision
  • Choose the most appropriate response type for each action
  • Include relevant flags to communicate action characteristics
  • Add contextual metadata to help users make informed decisions
  • Keep attachments small and relevant