Table of Contents

HTTP Headers & User-Agent

CobaltPdf lets you control the browser's User-Agent string and inject arbitrary HTTP request headers that are sent with every request Chromium makes during a render — the initial page navigation and all sub-resource fetches (CSS, images, scripts, XHR/fetch calls, etc.).

This is useful for:

  • Passing bearer tokens or API keys to authenticated pages
  • Sending tenant or correlation identifiers
  • Overriding Accept-Language for locale-specific rendering
  • Spoofing a mobile User-Agent to get a different page layout
  • Bypassing bot-detection that checks the User-Agent string

User-Agent

By default, Chromium sends its own User-Agent. Call WithUserAgent to override it for a render:

var pdf = await renderer
    .WithUserAgent("Mozilla/5.0 (compatible; MyReportBot/1.0)")
    .RenderUrlAsPdfAsync("https://example.com/report");

The string is sent as-is with every HTTP request, exactly as a real browser would send it.

Common use cases

// Present as a mobile browser (triggers responsive/mobile layout)
renderer.WithUserAgent(
    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) " +
    "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1");

// Identify your service to the target server
renderer.WithUserAgent("InvoiceService/3.2 (+https://mycompany.com/bot)");

// Bypass a basic bot-detection check that blocks headless Chromium
renderer.WithUserAgent(
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " +
    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36");

Extra HTTP Headers

Single header — WithHttpHeader

Add or overwrite one header at a time. Call it multiple times to set several headers independently:

var pdf = await renderer
    .WithHttpHeader("Authorization", "Bearer eyJhbGci...")
    .RenderUrlAsPdfAsync("https://api.example.com/report");

Multiple headers at once — WithHttpHeaders

Pass a dictionary when you have several headers to set in one call:

var pdf = await renderer
    .WithHttpHeaders(new Dictionary<string, string>
    {
        ["Authorization"]   = "Bearer eyJhbGci...",
        ["X-Api-Key"]       = "my-secret-key",
        ["Accept-Language"] = "fr-FR,fr;q=0.9",
        ["X-Tenant-Id"]     = "acme-corp"
    })
    .RenderUrlAsPdfAsync("https://example.com/report");

Chaining individual calls

WithHttpHeader and WithHttpHeaders can be freely mixed and chained:

var pdf = await renderer
    .WithHttpHeader("X-Tenant-Id",   "acme-corp")
    .WithHttpHeader("X-Request-Id",  Guid.NewGuid().ToString())
    .WithHttpHeaders(sharedHeaders)       // merge a shared base dictionary
    .RenderUrlAsPdfAsync("https://example.com/report");

If the same header name is set more than once (via multiple calls), the last value wins.

Note

Headers are sent with every request the browser makes during the render — the initial page navigation and all sub-resources. They override any default headers Chromium would normally send.

Combining Headers, User-Agent, Cookies, and Storage

All browser context options can be freely combined in a single render chain:

var pdf = await renderer
    .WithUserAgent("ReportingService/2.0")
    .WithHttpHeader("Authorization",  "Bearer eyJhbGci...")
    .WithHttpHeader("Accept-Language", "en-GB,en;q=0.9")
    .AddCookie("session", "abc123", ".example.com")
    .AddLocalStorage("theme", "dark")
    .RenderUrlAsPdfAsync("https://example.com/dashboard");

JSON / Microservice

When using CobaltPDF.Requests to send render jobs over HTTP, set the same options in your JSON payload:

{
  "url": "https://example.com/report",
  "userAgent": "Mozilla/5.0 (compatible; MyReportBot/1.0)",
  "extraHeaders": {
    "Authorization":   "Bearer eyJhbGci...",
    "Accept-Language": "en-GB,en;q=0.9",
    "X-Tenant-Id":     "acme-corp"
  }
}

Or in C# with PdfRequest:

var request = new PdfRequest
{
    Url       = "https://example.com/report",
    UserAgent = "Mozilla/5.0 (compatible; MyReportBot/1.0)",
    ExtraHeaders = new()
    {
        ["Authorization"]   = "Bearer eyJhbGci...",
        ["Accept-Language"] = "en-GB,en;q=0.9"
    }
};

var pdf = await request.ExecuteAsync(renderer, cancellationToken);

API Reference

Method Description
WithUserAgent(string userAgent) Overrides the browser User-Agent for this render.
WithHttpHeader(string name, string value) Adds or overwrites a single HTTP request header.
WithHttpHeaders(IDictionary<string, string> headers) Merges a dictionary of headers; existing keys are overwritten.

See the API reference for full parameter details.