Custom headers

Use the headers field to forward custom HTTP headers with a request. This is supported for direct (request-based) fetches.

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/protected",
    "headers": { "X-API-Key": "abc123", "X-Request-ID": "req-456" }
  }'

Conditional requests

Send If-None-Match or If-Modified-Since with a validator from an earlier response. For example:

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/catalog.json",
    "headers": { "If-None-Match": "\"catalog-v1\"" }
  }'

When the resource has not changed, the JSON response keeps the origin's status and validators:

{
  "statusCode": 304,
  "headers": {
    "etag": ["\"catalog-v1\""],
    "last-modified": ["Sun, 30 Aug 2026 12:00:00 GMT"]
  },
  "data": ""
}

Keep the body and headers.etag[0] or headers["last-modified"][0] from the earlier response. On a 304, reuse that body. String does not store the body or validators for you.

Rules

• Header names must be non-empty, at most 256 characters, and use only the token characters HTTP allows: letters, digits, and ! # $ % & ' * + - . ^ _ ` | ~.
• Header names are case-insensitive, so sending the same name twice in different case (Cookie and cookie) is rejected.
• Header values may be up to 32,768 characters and cannot contain control characters such as CR, LF, or NUL. Tabs are allowed.
• Maximum 50 custom headers per request.

A request that breaks a rule returns a 400 whose error names the header, for example Header "Cookie" value is 40002 characters; the limit is 32768.

Forbidden headers

These headers are managed by the service and cannot be set:

proxy-authorization, proxy-authenticate, proxy-connection, connection, transfer-encoding, content-length, te, upgrade, keep-alive, trailer, host.

Non-ASCII header values

A header value is sent as octets, one byte per character, so a value may use characters up to U+00FF (Latin-1, such as café). A value containing any character above U+00FF, such as an emoji, € or CJK text, returns a 400 that names the header:

Header "X-Probe" value contains a character above U+00FF; a header value is octets, so percent-encode or otherwise ASCII-encode it

Percent-encode such a value, or encode it some other way the destination expects, before sending it.

Conditional revalidation

For a repeat GET, pass the destination's validator back as If-None-Match, If-Modified-Since, or both:

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/catalog.json",
    "headers": { "If-None-Match": "\"catalog-v3\"" }
  }'

The destination's status remains inside the successful Web Access response. With the default json format, a not-modified result carries "statusCode": 304 and the destination's headers inside an HTTP 200 response, and data is empty because a 304 has no body. Branch on statusCode rather than on data: keep the previous body in your own store and reuse it when statusCode is 304. Web Access does not store the body in this mode.

Destination validators are available in the JSON envelope's headers and are also mirrored as x-origin-etag and x-origin-last-modified. For raw and markdown, read the destination status from x-status-code. The origin ETag is never assigned to the API response's ETag header because those formats may compress or transform the body.

A 304 is a successful request and bills at the normal rate for the fetch method and proxy zone. Conditional revalidation saves destination load and transferred bytes, not credits.