Breakpoints

Breakpoints let you pause HTTP traffic mid-flight, inspect the request or response, make changes, and then resume or drop it entirely. This gives you interactive, real-time control over individual requests — useful for debugging authentication flows, testing edge cases, or manipulating specific API calls on the fly.

Paid feature — requires a license with breakpoint editing capability.

Concepts

A breakpoint rule defines which traffic to pause using the same DSL match expressions used by interceptors. Each rule specifies a phase:

Phase	What pauses
`request`	The outgoing request is paused before it reaches the server
`response`	The server response is paused before it reaches the client
`both`	Both phases are paused independently

When a request matches a breakpoint rule, it becomes a pending breakpoint — held in memory until you resolve it (resume, modify, or drop).

Pending breakpoints have a configurable timeout. If not resolved before the timeout, the request is forwarded unchanged.

CLI

Create a breakpoint rule


apxy breakpoint add \
  --name "pause-auth" \
  --match "path contains /api/auth" \
  --phase request \
  --timeout 30000

Flag	Default	Description
`--name`	—	Rule name (required)
`--match`	—	DSL match expression (required)
`--phase`	`both`	`request`, `response`, or `both`
`--timeout`	`30000`	Timeout in milliseconds before auto-resume

List breakpoint rules


apxy breakpoint list

Remove a rule


apxy breakpoint remove --id <rule-id>

Enable / disable a rule


apxy breakpoint enable --id <rule-id>
apxy breakpoint disable --id <rule-id>

View pending breakpoints

List requests currently paused at a breakpoint:


apxy breakpoint pending

Resolve a pending breakpoint

Resume, modify, or drop a paused request:


# Resume unchanged
apxy breakpoint resolve --id <pending-id>
 
# Modify the response before resuming
apxy breakpoint resolve --id <pending-id> \
  --status 403 \
  --body '{"error": "forbidden"}'
 
# Drop the request entirely
apxy breakpoint resolve --id <pending-id> --drop

Flag	Default	Description
`--id`	—	Pending breakpoint ID (required)
`--status`	(unchanged)	Override response status code
`--headers`	(unchanged)	JSON object of headers to set
`--body`	(unchanged)	Override response body
`--drop`	`false`	Drop the request without forwarding

Web API

Method	Endpoint	Description
`GET`	`/api/v1/breakpoints`	List all breakpoint rules
`POST`	`/api/v1/breakpoints`	Create a new rule
`PUT`	`/api/v1/breakpoints/{id}/enable`	Enable a rule
`PUT`	`/api/v1/breakpoints/{id}/disable`	Disable a rule
`DELETE`	`/api/v1/breakpoints/{id}`	Delete a rule
`GET`	`/api/v1/breakpoints/pending`	List pending (paused) requests
`POST`	`/api/v1/breakpoints/{id}/resolve`	Resume or drop a pending request

Use Cases

Debug an authentication flow

Pause the login request, inspect the payload, and verify tokens before they reach the server:


apxy breakpoint add \
  --name "inspect-login" \
  --match "path == /api/auth/login && method == POST" \
  --phase request

Test error handling

Pause a response and change the status code to simulate a server error:


apxy breakpoint add \
  --name "force-500" \
  --match "path contains /api/payments" \
  --phase response
 
# When a request is caught:
apxy breakpoint resolve --id <pending-id> \
  --status 500 \
  --body '{"error": "internal server error"}'

Inspect a specific request before it fires

Pause all requests to a third-party API to verify exactly what’s being sent:


apxy breakpoint add \
  --name "check-stripe" \
  --match "host == api.stripe.com" \
  --phase request \
  --timeout 60000