OxyKit.Render

Document render engine for the OxyKit suite: an HTTP sidecar that turns JSON into PDF, XLSX, CSV, or HTML.

License: MIT · Org: oxykit-dev · Site: oxykit.dev
Releases: app zips · Client: OxyKit.Render.Client
Related: OxyKit.Flow · integrators use Client only (never OxyKit.Render.Core)

Quick start

Requires .NET 10 SDK.

dotnet run --project src/OxyKit.Render.Api

URL / header	Purpose
http://localhost:5066	API
X-OxyKit-Render-Key: dev-local-key	Dev API key (appsettings.Development.json). A non-empty key header is the only credential checked
Authorization: Bearer	Mail JWT when Security:Jwt matches Mail (Admin pack write, Admin|User pack read, Admin|User|Sender render)
GET /health	Anonymous
X-Correlation-Id	Optional; echoed on every response (generated if omitted)
/scalar, /openapi/v1.json	OpenAPI UI + JSON (Development only)
/formats, /templates, /render/{input}/{output}	Authenticated (+ /v1/... aliases)

dotnet test tests/OxyKit.Render.Api.Tests/OxyKit.Render.Api.Tests.csproj
dotnet test tests/OxyKit.Render.Client.Tests/OxyKit.Render.Client.Tests.csproj

Smoke: import hoppscotch/ collection + env → OxyKit.Render Local → run folders in order.

Observability: NuGet OxyKit.Observability (JSON stdout + correlation; no OxyKit.OpenTelemetry on Render). Docs: oxykit.dev/guide/observability.

curl -X POST "http://localhost:5066/render/table/html" \
  -H "Content-Type: application/json" \
  -H "X-OxyKit-Render-Key: dev-local-key" \
  -d '{"sheets":[{"name":"Orders","headers":["Id","Customer","Total"],"rows":[[1,"Acme",120.5],[2,"Beta",80]]}]}' \
  --output orders.html

NuGet (Client)

dotnet add package OxyKit.Render.Client

Also: OxyKit.Render.Contracts (transitive). Packable packages ship Client + Contracts only — Core stays host-internal. Tag v* → docs/NUGET_PUBLISH.md.

.NET Framework 2.0 / 4.5+: do not use the Client package — call HTTP per the Framework HOW-TO.

Local suite checkout (optional):

<ProjectReference Include="..\OxyKit.Render\src\OxyKit.Render.Client\OxyKit.Render.Client.csproj" />

Transforms

Route	Input	Output
POST /render/html/pdf	raw HTML content	PDF
POST /render/template/html	templateId + JSON data	HTML
POST /render/template/pdf	templateId + JSON data	PDF
POST /render/csv/pdf	CSV content	PDF
POST /render/csv/xlsx	CSV content	XLSX
POST /render/table/html	structured sheets	HTML
POST /render/table/pdf	structured sheets	PDF
POST /render/table/xlsx	structured sheets	XLSX
POST /render/table/csv	exactly one sheet	CSV

Template helpers (qr, barcode, money, …, asset, include) and the invoice starter (templates/invoice/, multi-page sample-data.json): oxykit.dev/render/transforms. Pack upload is a zip with template.html + contract.json (GET|PUT|DELETE /templates/{id}, GET .../pack). Asset labels land under assets/ for {{ asset }}. Compose keeps packs on the render-templates volume.

Errors: { "error": "..." } (400 / 401 / 403 / 500). Layout and constraints: AGENTS.md.

Docs

Doc	Role
AGENTS.md	Layout, constraints, add-transform checklist
oxykit.dev/render	Product docs
oxykit.dev/guide/iis	Windows / IIS
hoppscotch/	Manual HTTP smoke
CHANGELOG.md	Keep a Changelog
/scalar · /openapi/v1.json	Live API shapes (Development)
LICENSE	MIT