Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt

Use this file to discover all available pages before exploring further.

HTTP buttons use {{name}} placeholders in the URL, headers, and request body. When you press the button, each placeholder is replaced with the corresponding argument value. The substitution is context-aware: the encoding applied depends on where in the request the placeholder appears.

​
How substitution works

At press time, Buttons walks the URL and body and replaces every {{name}} with the value of the name argument. The encoding is chosen based on position:
LocationEncoding
URL path segment (before ?)url.PathEscape
URL query parameter (after ?)url.QueryEscape
JSON body (Content-Type: application/json)JSON string escape (\", \\, control chars)
Form body (Content-Type: application/x-www-form-urlencoded)url.QueryEscape
Other body typesRaw (no encoding)

​
Examples

​
URL path injection

A user passes ../../etc/passwd as the file_id argument: 
Template:   https://api.example.com/files/{{file_id}}/download
Raw value:  ../../etc/passwd
Result:     https://api.example.com/files/..%2F..%2Fetc%2Fpasswd/download
PathEscape encodes the slashes, so the traversal attempt becomes a literal (non-functional) path segment.

​
URL query injection

A user passes q=real&admin=true as the query argument: 
Template:   https://api.example.com/search?q={{query}}&limit=10
Raw value:  real&admin=true
Result:     https://api.example.com/search?q=real%26admin%3Dtrue&limit=10
QueryEscape encodes & and =, so the injected parameter never becomes a second query key.

​
JSON field injection

A user passes ","role":"admin as the username argument: 
Template:   {"username": "{{username}}", "action": "read"}
Raw value:  ","role":"admin
Result:     {"username": "\",\"role\":\"admin", "action": "read"}
JSON string escaping turns the quotes and commas into escape sequences, preventing the injected text from breaking out of the string field.

​
Headers

Header values also support {{arg}} substitution but are not encoded — they are passed as-is. This is appropriate for values like bearer tokens and API keys where encoding would break the value.
If you need to pass a literal {{ or }} in a URL or body, escape it as \{{ and \}}.

​
Raw body types

For bodies with a Content-Type other than application/json or application/x-www-form-urlencoded, Buttons inserts values without encoding. Use this only when you control the full body format and know the values are safe.
Raw substitution provides no injection protection. If the body format has its own injection risks (e.g. XML, LDAP query syntax), validate or sanitize argument values before they reach the button.