Debug an HTTP API with a CLI

---
name: debug-http-api-workflow
description: "Reproduce one request with explicit method, headers, body, timeout, and saved response before changing the server or client."
---

# Debug an HTTP API

## Intended outcome

Identify whether a failure comes from transport, authentication, request shape, server behavior, or response parsing.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **curl** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 8.7.1 recorded)
  - Install: `brew install curl`
  - Authentication: none, basic, bearer token, client certificate, netrc
  - Minimum permissions: Pass scoped tokens through environment-backed headers and never print request secrets.
- **HTTPie** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `pipx install httpie`
  - Authentication: none, basic, bearer token, auth plugins, sessions
  - Minimum permissions: Use environment-backed headers and store sessions outside the repository.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Endpoint and method
- redacted request headers
- request body
- expected status and response shape

## Output contract

- Reproducible command
- status and headers
- saved response body
- fault hypothesis

## Safe workflow

1. **Build a safe reproduction** — Use a non-secret environment variable for authentication and an explicit timeout.
   - Input: Endpoint, method, headers, and body
   - Output: Reviewable request command
   - Risk: `read-only`
   - Command: `curl --fail-with-body --max-time 20 -D headers.txt -o response.json "$API_URL"`
2. **Capture the response** — Save headers and body separately, then validate JSON without dumping credentials.
   - Input: HTTP response
   - Output: Status, headers, parsed body, and exit code
   - Risk: `local-write`
   - Command: `jq . response.json`
3. **Compare and isolate** — Change one input at a time and distinguish client errors from server errors and network failures.
   - Input: Baseline request and expected contract
   - Output: Smallest failing case and likely fault layer
   - Risk: `read-only`

## Ask before proceeding

- Calling endpoints that create, update, delete, charge, send, or deploy
- Using production credentials or customer data
- Retrying a non-idempotent request

## Rollback

- Use a read-only endpoint for the baseline
- Delete local response files containing sensitive data
- For approved writes, capture the resource ID and documented reversal path first

## Official sources

- [curl manual](https://curl.se/docs/manpage.html) — Official HTTP options, output handling, retries, and failure semantics.
- [HTTPie CLI documentation](https://httpie.io/docs/cli) — Official request syntax, sessions, authentication, and output documentation.
- [jq manual](https://jqlang.github.io/jq/manual/) — Official filters, input modes, exit status, and JSON transformation reference.