API buttons - Buttons

API buttons send an outbound HTTP request every time you press them. The URL, method, headers, and body are all stored in the button spec.

Basic GET

buttons create get-user \
  --url 'https://api.example.com/users/{{user_id}}' \
  --method GET \
  --arg user_id:string:required \
  -d "Fetch a user by ID"

Press it:

buttons press get-user --arg user_id=42

The {{user_id}} placeholder in the URL path is replaced with the value you pass. Values in path segments are encoded with PathEscape to prevent injection.

POST with a body

buttons create create-issue \
  --url 'https://api.github.com/repos/{{owner}}/{{repo}}/issues' \
  --method POST \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --body '{"title": "{{title}}", "body": "{{description}}"}' \
  --arg owner:string:required \
  --arg repo:string:required \
  --arg token:string:required \
  --arg title:string:required \
  --arg description:string:optional \
  -d "Open a GitHub issue"

Context-aware encoding

{{arg}} substitution is aware of where in the request the value appears:

Location	Encoding applied
URL path segment	`url.PathEscape`
URL query parameter	`url.QueryEscape`
JSON body (`Content-Type: application/json`)	JSON string escape
Form body (`Content-Type: application/x-www-form-urlencoded`)	`url.QueryEscape`

This means a value like O'Reilly & Sons is safe to pass into a JSON body or a query string without manual escaping. See template encoding for the full details.

Custom headers

Pass --header once per header. Headers support {{arg}} substitution just like the URL and body:

buttons create list-repos \
  --url 'https://api.github.com/users/{{username}}/repos' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Accept: application/vnd.github+json' \
  --arg username:string:required \
  --arg token:string:required

Response size limit

Responses are capped at 10 MB by default. Override with --max-response-size, which accepts a size with an optional unit suffix (B, K/KB, M/MB, G/GB; a bare number means bytes). The hard ceiling is 2 GB.

buttons create large-export \
  --url 'https://api.example.com/export' \
  --max-response-size 50M \
  -d "Download up to 50 MB"

Private network targets

By default, HTTP buttons block requests to private network ranges (loopback, RFC 1918, link-local). To allow a localhost or intranet target, pass --allow-private-networks at create time:

buttons create local-health \
  --url 'http://127.0.0.1:8080/health' \
  --allow-private-networks \
  -d "Check local service health"

Only use --allow-private-networks for buttons that target your own infrastructure. See SSRF protection for the full threat model.

URL and body templates — how {{arg}} substitution works
SSRF protection — private network blocking
Arguments — declare typed args

​Basic GET

​POST with a body

​Context-aware encoding

​Custom headers

​Response size limit

​Private network targets

​Related

Basic GET

POST with a body

Context-aware encoding

Custom headers

Response size limit

Private network targets

Related