Skip to main content
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:
LocationEncoding applied
URL path segmenturl.PathEscape
URL query parameterurl.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 (value in bytes): 
buttons create large-export \
  --url 'https://api.example.com/export' \
  --max-response-size 52428800 \
  -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.