API URL
POST /api/v1/ping-human/escalations, /api/v1/ping-human/escalations/:id, /reply/:token (gateway /r/:token)
Headers
Code
Content-Type: application/jsonBody Parameters
Param
Type
Description
X_DatpaqId
required
string
Owner identity supplied by gateway for agent operations
title
required
string
Escalation title shown in notifications (1-200 chars)
context
required
string
Decision context shown only on reply page (1-8000 chars escaped)
options
optional
array
2-6 choices of id/label with bounded formats
fields
optional
array
Up to 5 inputs with name type text or number label and required flag
channels
required
array
1-3 Slack or email notification channels
ttl_seconds
optional
number
Escalation lifetime 60-86400 (default 3600)
callback
optional
object
Callback URL and 16-128 character secret; URL SSRF-checked and secret encrypted
id
required
string
Escalation ID path parameter
token
required
string
Single-use reply token path parameter
Example Request
Code
POST https://datpaq.com/api/v1/ping-human/escalations?api_key=your-api-key | Headers: X-DatpaqId: qa-user | Body: {"title":"Approve?","context":"Review the requested action.","options":[{"id":"approve","label":"Approve"},{"id":"deny","label":"Deny"}],"channels":[{"type":"email","to":"qa@example.com"}],"ttl_seconds":3600}Successful Response
Status
HTML
200 OKBody
Code
{
"id": "esc_00000000-0000-0000-0000-000000000000",
"status": "pending",
"poll_url": "/api/v1/ping-human/escalations/esc_00000000-0000-0000-0000-000000000000",
"expires_at": "2026-10-14T13:00:00.000Z",
"poll_interval_seconds": 5,
"correlationId": "req_abc123"
}Field
Type
id
string
status
string
poll_url
string
expires_at
string
poll_interval_seconds
number
reply_url
string
title
string
created_at
string
response
object
response_option_id
string
response_fields
object
response_responded_at
string
success
boolean
retryAfter
number
correlationId
string
database
string
callbacksEnabled
boolean
service
string
version
string
error
object
metadata
object
updatedAt
string
processingTime
string
Error Response
Example
Code
HTTP 400 ValidationError: Joi failure non-allowlisted Slack host or SSRF-blocked callback URL — Code BLOCKED_URL for SSRF rejections; HTTP 401 AuthenticationError: Missing gateway identity or invalid API key — Request rejected before processing; HTTP 404 NotFound: Unknown escalation not owner or unknown reply token — Constant-time lookup prevents existence leaks; HTTP 409 ConflictError: Already resolved/cancelled or lost single-use race — Applies to API and reply page; HTTP 410 ExpiredError: Reply link expired — Server-rendered expired page; HTTP 429 RateLimitError: Create poll or reply limit exceeded — retryAfter Unix epoch reset time is included in JSON responses; HTTP 503 CallbackUnavailable: PINGHUMAN_ENC_KEY not configured with callback supplied — Code CALLBACK_UNAVAILABLE; HTTP 503 DatabaseUnavailable: Database connection unavailable during an escalation operation — Escalation storage is temporarily unavailable; HTTP 503 ReplyUnavailable: Database unavailable while rendering or submitting a reply — HTML unavailable page is returned; HTTP 500 InternalError: Unexpected failure — Escalation could not be processedLast Updated: May 4, 2026