POST /encode_uri • Credits: 0.5 credits per call

Encode URI percent-encodes one string, so that the string is safe inside a URL query parameter or a path segment. The response holds the trimmed input in original_value and the encoded text in encoded_value. Encode URI costs 0.5 credits per call, that is $0.01.

What does Encode URI do?

Encode URI turns text into a form that a URL accepts. A URL gives a special meaning to characters such as &, =, ? and /. Text that holds one of those characters breaks the URL. Encode URI replaces every character outside the RFC 3986 unreserved set with a percent sign and the hexadecimal value of each UTF-8 byte. Encode URI runs inside RichAPI and calls no external service. The maximum input size is 1 MB.

Which endpoint does Encode URI use?

Method: POST
URL: https://api.richapi.ai/api/v1/encode_uri
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 0.5 credits per call

How to send an Encode URI request

Copy your API key from the RichAPI dashboard.
Set the value parameter to the text that belongs inside the URL.
Send a POST request to https://api.richapi.ai/api/v1/encode_uri.
Send the API key in the x-api-key header.
Read the encoded_value field from the response.
Put encoded_value into your URL after the parameter name.

cURL

curl -X POST https://api.richapi.ai/api/v1/encode_uri   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "value": "hello world & foo=bar"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/encode_uri",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "value": "hello world & foo=bar",
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/encode_uri", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    value: "hello world & foo=bar",
  }),
});

const data = await response.json();
console.log(data);

Which parameters does Encode URI accept?

The table holds the fields of the HTTP request body. Send this name to https://api.richapi.ai/api/v1/encode_uri.

Parameter	Type	Required	Default	Description
`value`	string	Yes	`""`	The text to percent-encode. The maximum length is 1,048,576 characters.

The RichAPI endpoint catalog records "" as the default of value. The parameter is required, so the default never applies. Encode URI removes the whitespace at the start and at the end of value before it encodes the text. A value that holds only whitespace returns a 400 error.

The dashboard, the MCP tool encode_uri, and the n8n operation encode_uri use the same name value. No name mapping is needed.

Which characters does Encode URI escape?

Encode URI escapes every printable ASCII character in the next table. Encode URI writes the hexadecimal digits in uppercase, for example %2A and not %2a.

Character	Name	Encoded as
(space)	Space	`%20`
`!`	Exclamation mark	`%21`
`"`	Double quote	`%22`
`#`	Hash	`%23`
`$`	Dollar sign	`%24`
`%`	Percent sign	`%25`
`&`	Ampersand	`%26`
`'`	Single quote	`%27`
`(`	Left parenthesis	`%28`
`)`	Right parenthesis	`%29`
`*`	Asterisk	`%2A`
`+`	Plus sign	`%2B`
`,`	Comma	`%2C`
`/`	Slash	`%2F`
`:`	Colon	`%3A`
`;`	Semicolon	`%3B`
`<`	Less-than sign	`%3C`
`=`	Equals sign	`%3D`
`>`	Greater-than sign	`%3E`
`?`	Question mark	`%3F`
`@`	At sign	`%40`
`[`	Left square bracket	`%5B`
`\`	Backslash	`%5C`
`]`	Right square bracket	`%5D`
`^`	Caret	`%5E`
`	Backtick	`%60`
`{`	Left curly brace	`%7B`
`\\|`	Vertical bar	`%7C`
`}`	Right curly brace	`%7D`

Encode URI escapes a control character in the same way. A tab becomes %09. A newline becomes %0A.

Encode URI escapes a non-ASCII character as its UTF-8 bytes. The letter é becomes %C3%A9. The word 日本 becomes %E6%97%A5%E6%9C%AC.

Which characters does Encode URI leave unchanged?

Encode URI leaves four groups of characters unchanged.

Characters	Group
`A` to `Z`	Uppercase ASCII letters
`a` to `z`	Lowercase ASCII letters
`0` to `9`	ASCII digits
`-_.~`	Hyphen, underscore, period, tilde

Those four groups are the RFC 3986 unreserved set. Encode URI leaves no reserved character unchanged. Encode URI escapes all eighteen reserved characters. The reserved set is :/?#[]@!$&'()*+,; and =.

Is Encode URI the same as encodeURI or encodeURIComponent?

Encode URI behaves like JavaScript encodeURIComponent, and not like JavaScript encodeURI. JavaScript encodeURI keeps the reserved delimiters of a URL, because it encodes a whole URL. Encode URI escapes those delimiters, because it encodes one parameter value.

Encode URI is stricter than encodeURIComponent on five characters.

Characters	RichAPI Encode URI	JavaScript `encodeURI`	JavaScript `encodeURIComponent`
`A` to `Z`, `a` to `z`, `0` to `9`	Unchanged	Unchanged	Unchanged
`-_.~`	Unchanged	Unchanged	Unchanged
`!*'()`	Escaped	Unchanged	Unchanged
`;/?:@&=+$,#`	Escaped	Unchanged	Escaped
Space	`%20`	`%20`	`%20`

Encode URI matches this JavaScript function exactly.

const richApiEncode = (value) =>
  encodeURIComponent(value.trim()).replace(
    /[!'()*]/g,
    (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
  );

Encode URI matches this Python expression exactly.

import urllib.parse

encoded = urllib.parse.quote(value.strip(), safe="")

What does Encode URI return?

The next block is an example. It shows the response for the request body {"value": "hello world & foo=bar"}.

{
  "original_value": "hello world & foo=bar",
  "encoded_value": "hello%20world%20%26%20foo%3Dbar"
}

Which fields does the Encode URI response hold?

Field	Type	Description
`original_value`	string	The input text after RichAPI removes the whitespace at the start and at the end.
`encoded_value`	string	The percent-encoded form of `original_value`.

How do I build a Google search URL with Encode URI?

A search URL carries the query text inside a parameter. A query that holds spaces, quotes, parentheses and a colon breaks the URL. Encode URI returns the safe form of that text.

Write the search query as plain text.
Send the query text as the value parameter.
Read encoded_value from the response.
Join the base URL, the parameter name, and encoded_value.

Send this request.

curl -X POST https://api.richapi.ai/api/v1/encode_uri   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "value": "\"Head of Sales\" AND (SaaS OR Fintech) site:linkedin.com/in"
  }'

Encode URI returns this example response.

{
  "original_value": "\"Head of Sales\" AND (SaaS OR Fintech) site:linkedin.com/in",
  "encoded_value": "%22Head%20of%20Sales%22%20AND%20%28SaaS%20OR%20Fintech%29%20site%3Alinkedin.com%2Fin"
}

Join the base URL and encoded_value to get the final link.

https://www.google.com/search?q=%22Head%20of%20Sales%22%20AND%20%28SaaS%20OR%20Fintech%29%20site%3Alinkedin.com%2Fin

The same step builds a LinkedIn Sales Navigator search URL. The valueHead of Growth returns the encoded_valueHead%20of%20Growth.

https://www.linkedin.com/sales/search/people?keywords=Head%20of%20Growth

This Node.js sample runs the whole flow in one step.

const response = await fetch("https://api.richapi.ai/api/v1/encode_uri", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    value: '"Head of Sales" AND (SaaS OR Fintech) site:linkedin.com/in',
  }),
});

const data = await response.json();
console.log(`https://www.google.com/search?q=${data.encoded_value}`);

CAUTION: Send the parameter value, and not the whole URL. Encode URI escapes : and /, so a whole URL becomes one escaped string and stops working as a link.

How much does Encode URI cost?

Encode URI costs 0.5 credits per call. At $0.02 a credit, the rate on the 1,000 and 5,000 credit packs, one call costs $0.01. Larger packs cost less per credit. The length of value does not change the price. A 3-character input and a 1 MB input both cost 0.5 credits.

Calls	Credits	Cost
1	0.5	$0.01
10	5	$0.10
100	50	$1.00
1,000	500	$10.00
10,000	5,000	$100.00
50,000	25,000	$500.00

RichAPI charges the credits once for each call that returns a 2xx status.

Which errors can Encode URI return?

Status	Meaning	What to do
`400`	The request body holds no `value` field.	Add the `value` field to the request body.
`400`	The `value` field is empty after RichAPI removes the whitespace.	Send a `value` with one non-whitespace character or more.
`400`	The `value` field is longer than 1,048,576 characters.	Split the text, then send each part in its own request.
`400`	The request body is absent, is not valid JSON, or is not a JSON object.	Send a JSON object and the header `Content-Type: application/json`.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has too few credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`405`	The request used a method other than `POST`.	Send the request with the `POST` method.
`429`	Too many requests.	Wait, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

RichAPI charges credits on a 2xx response only. A 400, 401, 402, 403, 405, 429 or 500 response costs 0 credits.

Frequently asked questions

Does Encode URI escape a slash and an ampersand?

Yes. Encode URI escapes / as %2F and & as %26. Encode URI escapes every RFC 3986 reserved character, because it encodes one parameter value and not a whole URL.

Is Encode URI the same as JavaScript encodeURIComponent?

Almost. Encode URI escapes the five characters !, *, ', ( and ), and JavaScript encodeURIComponent leaves those five unchanged. Every other character gets the same treatment in both.

When is Encode URI worth 0.5 credits?

Most programming languages hold a built-in encoder, for example encodeURIComponent in JavaScript and urllib.parse.quote in Python. In your own code, call the built-in function and pay nothing. Encode URI earns its 0.5 credits inside a no-code automation, an n8n workflow, or an MCP agent that has no encoder of its own.

Does Encode URI remove the spaces around my value?

Yes. Encode URI removes the whitespace at the start and at the end of value before it encodes the text. The original_value field in the response holds that trimmed text. A space inside the text stays, and Encode URI returns it as %20.

Can Encode URI decode a percent-encoded string?

No. Encode URI encodes text only, and RichAPI publishes no decode endpoint. To read %20 back as a space, call the decoder of your own language, for example decodeURIComponent in JavaScript.

What happens if I send a number instead of a string?

Encode URI returns status 400 with the message Invalid value for value: expected string, and the call costs no credit. Send value as a JSON string, for example "42".

Encode URI API