base64_encode_url_safe

Encode a UTF-8 string to Base64 using the URL-safe alphabet (RFC 4648 §5). The URL-safe alphabet replaces + with - and / with _, making the output safe for use in URLs, query parameters, JWT tokens, and filenames without percent-encoding. Output always includes = padding.

For standard Base64 encoding (uses + and /), use base64_encode instead.

Parameters

Parameter	Type	Required	Description
input	string	Yes	The UTF-8 string to encode.

Response

Field	Type	Description
output	string	The URL-safe Base64-encoded string.

Examples

Encode a string that produces - and _ in the output

The input hello~world contains a ~ whose encoding crosses the /(63) boundary, producing _ in the URL-safe alphabet instead of /:

{
	"input": "hello~world"
}

Result:

{
	"output": "aGVsbG9-d29ybGQ="
}

The ~ character encodes to > in the raw bytes, which produces + in standard Base64 and - in URL-safe Base64. Compare with base64_encode for the same input: aGVsbG9+d29ybGQ=.

Encode a string containing ~>? (shows both - and _)

{
	"input": "~>?"
}

Result:

{
	"output": "fj4_"
}

The / that standard Base64 would produce for this input becomes _ — safe for use in URLs and filenames with no percent-encoding required.

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	The input field is missing or not a string.	protocol error (invalid_params)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• The input must be valid UTF-8. Binary data cannot be encoded directly.
• Output always includes = padding — the output length is always a multiple of 4 characters.
• The URL-safe alphabet uses - and _ instead of + and /. Strings containing ~, >, ? or other characters that produce / in standard Base64 will produce _ instead — safe for URLs and filenames with no percent-encoding required.
• To decode URL-safe Base64, use base64_decode_url_safe.