CobaltPDF.Requests 1.3.0

CobaltPDF.Requests

Lightweight, serialisable request and response models for CobaltPDF — the .NET HTML-to-PDF library.

Install this package in client applications (web APIs, mobile backends, microservices) that send PDF generation requests over HTTP to a CobaltPDF rendering service. No Chromium or Playwright dependency — just ~50 KB of models.

[Client Application]                        [PDF Rendering Service]
CobaltPDF.Requests (~50 KB)  ── HTTP POST ──▶  CobaltPDF (full library)
  PdfRequest  → JSON                            CobaltEngine + Chromium
  PdfResponse ← JSON                            request.ExecuteAsync(engine)
  No Chromium, No Playwright

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

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

var request = new PdfRequest
{
    Url         = "https://myapp.com/invoice/42",
    PaperFormat = "A4",
    Header      = "<div style='font-size:10px;text-align:center;width:100%'>My Company</div>",
    Footer      = "<div style='font-size:10px;text-align:center;width:100%'>" +
                  "Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    Metadata    = new() { Title = "Invoice #42", Author = "Billing System" },
    Encryption  = new() { UserPassword = "open123", AllowPrinting = true },
    Cookies     = [new() { Name = "session", Value = "abc123", Domain = "myapp.com" }]
};

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();

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.