CobaltPDF.Requests 1.6.0

CobaltPDF.Requests

Generate PDFs from your app — without putting a browser in it.

CobaltPDF.Requests is a tiny (~50 KB) package of two plain C# models: PdfRequest and PdfResponse. Your app describes the PDF it wants as a PdfRequest, sends it as JSON to a CobaltPDF rendering service you host, and gets the finished PDF back.

The service does all the heavy lifting (Chromium or WebKit). Your web API, mobile backend, or serverless function stays small and fast — no Chromium, no rendering engine, no native libraries to install.

   YOUR APP                                   YOUR PDF SERVICE  (you host once)
   CobaltPDF.Requests · ~50 KB                CobaltPDF  or  CobaltPDF.WebKit
   no browser, no engine                      the real render engine + warm pool

      build a PdfRequest  ───── POST as JSON ─────▶   request.ExecuteAsync(engine)
      save the PDF        ◀───── PDF bytes ──────────   renders & returns the PDF

Engine-agnostic. The same serialised PdfRequest renders on a service backed by either CobaltPDF (Chromium) or CobaltPDF.WebKit — clients never need to know which engine is on the other end.

Installation

Client (web app, mobile backend, other service):

dotnet add package CobaltPDF.Requests

Rendering service (Azure Function, ASP.NET Core, AWS Lambda, worker):

dotnet add package CobaltPDF
# CobaltPDF.Requests models are included automatically

Quick start — client

Build a request with the fluent builder, POST it to your service, and save the PDF:

using CobaltPdf.Requests;
using System.Net.Http.Json;

var request = PdfRequest.ForUrl("https://myapp.com/invoice/42")
    .WithPaperFormat("A4")
    .WithHeader("<div style='font-size:10px;text-align:center;width:100%'>My Company</div>")
    .WithFooter("Page <span class='pageNumber'></span> of <span class='totalPages'></span>")
    .WithMetadata(m => { m.Title = "Invoice #42"; m.Author = "Billing System"; })
    .WithEncryption("open123")
    .AddCookie("session", "abc123", "myapp.com")
    .Build();

var httpResponse = await httpClient.PostAsJsonAsync("https://pdf-service/api/pdf", request);
httpResponse.EnsureSuccessStatusCode();

// Option A — raw PDF bytes (Content-Type: application/pdf)
byte[] pdfBytes = await httpResponse.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("invoice.pdf", pdfBytes);

// Option B — PdfResponse JSON (Content-Type: application/json)
var pdfResponse = await httpResponse.Content.ReadFromJsonAsync<PdfResponse>();
byte[] pdfBytes2 = pdfResponse!.ToBytes();

Prefer plain objects? The object-initializer style works identically — see Two ways to build a request below.

Two ways to build a request

PdfRequest is a plain serialisable model — use whichever style you prefer. Both produce the exact same request (identical JSON on the wire).

Fluent builder (recommended) — mirrors the CobaltEngine fluent API, so authoring a request reads the same as rendering one:

var request = PdfRequest.ForUrl("https://bbc.co.uk")   // or PdfRequest.ForHtml("<h1>Hi</h1>")
    .WithPaperFormat("A4")
    .WithMargins("15mm")
    .AddCookie("ckns_explicit", "1", ".bbc.co.uk")
    .WithHeader("<div style='font-size:9px;text-align:center;width:100%'>My Company</div>")
    .WithMetadata(m => { m.Title = "Invoice #42"; m.Author = "Billing System"; })
    .Build();                                           // returns a PdfRequest

.Build() returns an ordinary PdfRequest, so everything downstream (serialisation, ExecuteAsync on the server) is unchanged. Already have a PdfRequest? Call .ToBuilder() to tweak it fluently. The builder covers the whole model — WithLandscape, WithFooter, WithWatermark, WithWaitStrategy, WithLazyLoadPages, WithHttpHeader(s), AddLocalStorage/AddSessionStorage, WithEncryption, and more.

Object initializer — the classic style, idiomatic for data shapes:

var request = new PdfRequest
{
    Url         = "https://bbc.co.uk",
    PaperFormat = "A4",
    Margins     = new PdfRequestMargins { Top = "15mm", Right = "15mm", Bottom = "15mm", Left = "15mm" },
    Cookies     = { new PdfRequestCookie { Name = "ckns_explicit", Value = "1", Domain = ".bbc.co.uk" } }
};

Quick start — server

ASP.NET Core Minimal API

using CobaltPdf;
using CobaltPdf.Configuration;
using CobaltPdf.Extensions;
using CobaltPdf.Requests;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCobaltPdf(o =>
{
    CloudEnvironment.ConfigureForDocker(o);
    o.MaxSize = Math.Max(2, Environment.ProcessorCount);
});

var app = builder.Build();

CobaltEngine.SetLicense(app.Configuration["CobaltPdf:LicenseKey"]!);
await CobaltEngine.PreWarmAsync();

// POST /api/pdf → raw PDF bytes
app.MapPost("/api/pdf", async (PdfRequest request, CobaltEngine renderer, CancellationToken ct) =>
{
    var pdf = await request.ExecuteAsync(renderer, ct);
    return Results.File(pdf.BinaryData, "application/pdf", "output.pdf");
});

// POST /api/pdf/json → PdfResponse JSON (service-to-service)
app.MapPost("/api/pdf/json", async (PdfRequest request, CobaltEngine renderer, CancellationToken ct) =>
{
    var pdf = await request.ExecuteAsync(renderer, ct);
    return Results.Ok(PdfResponse.FromBytes(pdf.BinaryData));
});

app.Run();

Azure Function (Isolated Worker)

[Function("GeneratePdf")]
public async Task<HttpResponseData> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "pdf")]
    HttpRequestData req, CancellationToken ct)
{
    var request = await req.ReadFromJsonAsync<PdfRequest>();
    var pdf     = await request!.ExecuteAsync(_renderer, ct);

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "application/pdf");
    await response.Body.WriteAsync(pdf.BinaryData, ct);
    return response;
}

Note: Azure Functions Consumption Plan is not supported. Use the Premium Plan (EP1+) or Dedicated (App Service) Plan.

Client examples in other languages

TypeScript / JavaScript

const request = {
  url:         "https://myapp.com/invoice/42",
  paperFormat: "A4",
  landscape:   false,
  metadata:    { title: "Invoice #42", author: "Billing System" }
};

const response = await fetch("https://pdf-service/api/pdf", {
  method:  "POST",
  headers: { "Content-Type": "application/json" },
  body:    JSON.stringify(request)
});

const blob = await response.blob();
const url  = URL.createObjectURL(blob);
const a    = document.createElement("a");
a.href     = url;
a.download = "invoice.pdf";
a.click();

Python

import requests

payload = {
    "url":         "https://myapp.com/invoice/42",
    "paperFormat": "A4",
    "metadata":    { "title": "Invoice #42", "author": "Billing System" }
}

response = requests.post("https://pdf-service/api/pdf", json=payload)
response.raise_for_status()

with open("invoice.pdf", "wb") as f:
    f.write(response.content)

PdfRequest properties

Source (one required)

Layout

Headers & footers

Watermark

Wait strategy

HTTP & authentication

JavaScript

Lazy loading

Encryption

Metadata

PdfResponse

Returned by the rendering service after a successful render.

Helpers:

byte[]       bytes  = response.ToBytes();   // decode to raw bytes
MemoryStream stream = response.ToStream();  // decode to a MemoryStream

Factory (server-side):

var response = PdfResponse.FromBytes(pdf.BinaryData);

Returning the PDF

Your endpoint can respond in two ways:

Raw bytes — application/pdf

Best for browser downloads, mobile apps, and direct file saves.

return Results.File(pdf.BinaryData, "application/pdf", "output.pdf");

JSON — PdfResponse

Best for service-to-service calls where the caller needs to process or store the PDF.

return Results.Ok(PdfResponse.FromBytes(pdf.BinaryData));

Platform summary

Security considerations

• Authenticate every endpoint. The rendering service can reach any URL on its network — an unauthenticated endpoint is a security risk.
• Whitelist allowed domains if you don't control all callers, to prevent SSRF.
• Store license keys in secrets — Azure Key Vault, AWS Secrets Manager, or environment variables.
• Do not expose Html rendering publicly without sanitisation — arbitrary HTML can be used to render internal URLs.

Documentation

Full deployment guides (Azure Functions, AWS Lambda, ECS/Fargate), the complete JSON schema, and working server examples are available at:

cobaltpdf.com/docs/articles/cobalt-requests.html

License

See the CobaltPDF website for licensing details.