Docs/Pause requests

Pause Requests

The pause_request is the core entity in PausePoint. Creating one pauses your agent, sends a notification, and waits for a human response.

Status State Machine#

text

                ┌─────────────────────────────────────────┐
                │               CREATE                      │
                │         POST /v1/pause                   │
                └──────────────┬──────────────────────────┘
                               │
                               ▼
                          ┌─────────┐
                          │ pending │ ◄── polling happens here
                          └────┬────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                 │
              ▼                ▼                 ▼
        ┌──────────┐    ┌───────────┐    ┌───────────┐
        │responded │    │ timed_out │    │ cancelled │
        └──────────┘    └───────────┘    └───────────┘

Once a request leaves pending, it cannot change status again.

Create a Pause Request#

POST /v1/pause

Request Fields#

Field	Type	Required	Default	Description
`recipient`	string	Yes	—	Phone (E.164), email address, or Slack webhook URL
`channel`	string	Yes	—	`"sms"` \| `"email"` \| `"slack"`
`message`	string	Yes	—	The question shown to the human. Max 2000 chars.
`options`	string[]	Yes	—	2–5 answer choices. e.g. `["Approve", "Reject"]`
`allow_text_response`	bool	No	false	Show a freetext note input on the response page
`timeout_hours`	int	No	24	Hours before auto-timeout. Capped by plan.
`timeout_default`	string\|null	No	null	Option to auto-select on timeout. null = no auto-choice.
`metadata`	object	No	null	Arbitrary key-value data. Returned in webhooks and polls.

Channel-Specific Recipient Formats#

Channel	Recipient format	Example
sms	E.164 phone number	`"+15550100"`
email	Email address	`"cfo@company.com"`
slack	Slack incoming webhook URL	`"https://hooks.slack.com/services/..."`

Example — SMS#

bash

curl -X POST https://api.pausepoint.dev/v1/pause \
  -H "Authorization: Bearer $PP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+15550100",
    "channel": "sms",
    "message": "Your agent wants to send a $340 wire to Acme Corp. Approve?",
    "options": ["Approve", "Reject"],
    "timeout_hours": 4,
    "timeout_default": "Reject",
    "metadata": {"amount": 340, "recipient_name": "Acme Corp"}
  }'

Example — Email#

bash

curl -X POST https://api.pausepoint.dev/v1/pause \
  -H "Authorization: Bearer $PP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "cfo@company.com",
    "channel": "email",
    "message": "The sales agent has drafted a campaign email to 200 leads. Send it?",
    "options": ["Send it", "Edit first", "Cancel"],
    "timeout_hours": 24,
    "timeout_default": "Cancel"
  }'

Example — Slack#

bash

curl -X POST https://api.pausepoint.dev/v1/pause \
  -H "Authorization: Bearer $PP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "https://hooks.slack.com/services/T.../B.../...",
    "channel": "slack",
    "message": "Delete 14,000 stale user records from the test environment?",
    "options": ["Delete", "Keep", "Ask me tomorrow"],
    "timeout_hours": 8
  }'

Poll for Response#

GET /v1/pause/{pause_id}

Keep polling until status != "pending":

python

import requests, time

while True:
    result = requests.get(
        f"https://api.pausepoint.dev/v1/pause/{pause_id}",
        headers={"Authorization": f"Bearer {api_key}"}
    ).json()

    if result["status"] == "responded":
        decision = result["response_choice"]  # "Approve"
        break
    elif result["status"] in ("timed_out", "cancelled"):
        decision = result["response_choice"]  # timeout_default or None
        break

    time.sleep(5)

Response Fields#

Field	Type	Description
`pause_id`	UUID	Unique identifier
`status`	string	`pending` \| `responded` \| `timed_out` \| `cancelled`
`response_choice`	string\|null	The human's choice (or timeout_default)
`response_text`	string\|null	Freetext note if allow_text_response was true
`response_at`	ISO timestamp\|null	When the response was recorded
`expires_at`	ISO timestamp	When timeout fires
`metadata`	object\|null	Whatever you passed in

Metadata Field#

Pass any JSON object in metadata. It is returned unchanged in every poll response and webhook payload. Use it to correlate responses with your internal state:

json

{
  "metadata": {
    "agent_run_id": "run_abc123",
    "customer_id": "cust_9876",
    "amount_usd": 340
  }
}