URL Encode API: Complete Developer Guide

Need to safely pass data in URLs? This guide covers everything about URL encoding via API, including why encoding is necessary, which characters need escaping, and implementation examples in multiple programming languages.

What is URL Encoding?

URL encoding (also called percent encoding) converts characters that aren't allowed in URLs into a format that can be safely transmitted. Special characters are replaced with a % followed by their hexadecimal ASCII value.

Example: Hello World! becomes Hello%20World%21

Reserved Characters

These characters have special meaning in URLs and must be encoded when used as data:

General Delimiters

: / ? # [ ] @ - Used to separate URL components

Sub-Delimiters

! $ & ' ( ) * + , ; = - Used within URL components

Other Characters

Spaces become %20 or + (in query strings)

Using the URL Encode API

TinyFn provides a simple endpoint to URL encode strings:

POST https://api.tinyfn.io/v1/encode/url
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "text": "Hello World! How are you?"
}

{
  "encoded": "Hello%20World%21%20How%20are%20you%3F",
  "original": "Hello World! How are you?",
  "encoding": "utf-8"
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/encode/url',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: 'Hello World!' })
  }
);
const { encoded } = await response.json();
console.log(encoded); // Hello%20World%21

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/encode/url',
    headers={'X-API-Key': 'your-api-key'},
    json={'text': 'Hello World!'}
)
encoded = response.json()['encoded']
print(encoded)  # Hello%20World%21

cURL

curl -X POST "https://api.tinyfn.io/v1/encode/url" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World!"}'

Common Use Cases

• Query Parameters: Encode values before adding to query strings
• Path Segments: Safely include file names in URL paths
• Form Data: Encode form data for application/x-www-form-urlencoded
• API Calls: Encode parameters for third-party API requests
• Link Generation: Create shareable links with user content

Best Practices

1. Encode once: Don't double-encode - %20 would become %2520
2. UTF-8 first: Always encode strings as UTF-8 before URL encoding
3. Component-aware: Use different encoding for path vs query string
4. Decode on receive: Always decode URL parameters when processing

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-encode": {
      "url": "https://api.tinyfn.io/mcp/encode/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all encoding tools available via MCP in our Encoding MCP Tools for AI Agents guide.