Reports

Create reports, collaborate on the JSON payload, and generate PDFs into location documents.

Render a complete client document

Applications that already generate their own HTML can send the finished document to POST /v1/document-libraries/location/{locationId}/documents/render-pdf?folderPath=Aufmass. Use Content-Type: text/html; charset=utf-8 and place the complete HTML in the body. The maximum HTML size is 32 MiB. Embed CSS, fonts and images; scripts and external resource requests are disabled during rendering. Chromium uses the supplied print CSS, page sizes and page breaks, with background graphics enabled.

This endpoint requires LocationDocuments=Write at the exact destination folder, including current organization entitlements and any PAT restrictions. Use an empty folderPath for the document root. A successful response contains PDF bytes with Content-Type: application/pdf; it does not create a report, template or stored document. Upload the returned file through the document upload workflow using the same location and folder. Upload completion independently checks current write access and storage quota. Open the returned document ID after completion.

Rendering requires the configured Chromium background service. Unavailable service returns 503, busy capacity 429, and a rendering timeout 504. Treat all non-2xx responses as errors and never upload an error response as a PDF.

Overview

Reports use their own API routes.

  • GET /v1/reports/templates
  • GET /v1/reports/templates/{key}
  • POST /v1/reports/templates/users/me
  • POST /v1/reports/templates/organizations/{organizationId}
  • PUT /v1/reports/templates/{templateId}
  • DELETE /v1/reports/templates/{templateId}
  • GET /v1/reports/locations/{locationId}
  • POST /v1/reports/locations/{locationId}
  • GET /v1/reports/{reportId}
  • PUT /v1/reports/{reportId}
  • DELETE /v1/reports/{reportId}
  • POST /v1/reports/{reportId}/collaboration/bootstrap
  • POST /v1/reports/{reportId}/generate-pdf
  • GET /v1/reports/jobs/{jobId}

Workflow

  1. Create or list templates owned by an accessible organization. Private user templates remain available only to their owning interactive session for legacy compatibility.
  2. Load one template by key.
  3. Read contentTemplateJson from that template.
  4. Fill the JSON on the client, including normal fields, image references, and the main markdown body.
  5. Create a report row for the target location with that filled JSON.
  6. Edit the report JSON directly or bootstrap collaboration for that report.
  7. Call generate-pdf when the report is ready.
  8. Poll GET /v1/reports/jobs/{jobId} until the PDF is ready.

The editable report draft stays separate from the generated PDF. When generation finishes, the PDF appears in the location document library.

Access requirements

For organization-owned reports, PixService evaluates the exact current actor and the current PAT ceiling when a personal access token is used.

  • Discovering the location requires LocationView=Read.
  • Listing and reading reports and organization templates requires ReportsRead.
  • Creating, changing, deleting, or generating reports requires ReportsWrite.
  • Managing organization templates requires ReportTemplatesManage.
  • PDF publication requires LocationDocuments=Write at the exact destination folder path.
  • Referenced report images require LocationDocuments=Read at their exact source paths.
  • Organization branding is included only with OrganizationBrandingRead.

These are final tier-capped decisions. A PAT can only reduce the user's effective access. Private user-owned templates and legacy user-owned reports are session-only compatibility surfaces; PATs cannot use them and they never grant organization access.

Template Model

Each template record stores:

  • the template key and display name
  • the HTML shell template
  • the CSS stylesheet template
  • the CSS media type
  • contentTemplateJson, which is the JSON skeleton clients can fetch and fill
  • bodyFieldPath, which tells PixService where the main markdown body lives inside the report JSON

Templates can use values from the JSON payload plus reserved metadata under:

  • report.*
  • location.*
  • template.*
  • branding.*

The main report body is markdown stored inside the report JSON. Raw HTML in that markdown is preserved, so the body can mix markdown and HTML freely.

If a template leaves htmlLayoutTemplate empty, PixService uses a default wrapper layout.

Example image helpers:

{{ image "imageInputs.coverImage" }}

{{ image_list "imageInputs.gallery" 2 }}

Inside the HTML shell, body_html contains the rendered body content and stylesheet_css contains the rendered stylesheet.

Image Inputs

Image values can be:

  • a string path such as photos/cover.jpg
  • an object with documentPath and optional caption
  • an array of those values for image galleries

Preferred paths are stable location-document paths relative to documents/. If a document has multiple versions, omit the v00000001 segment and PixService uses the latest matching version.

Branding Variables

Branding is template-controlled. Templates receive a branding object and decide whether and where to place colors, names, or logos.

Typical examples:

  • branding.organization_name
  • branding.brand_name
  • branding.slogan
  • branding.primary_color
  • branding.secondary_color
  • branding.accent_color
  • branding.logo_data_url
  • branding.banner_data_url

For organization-owned locations, branding comes from the organization's branding settings when the current actor has OrganizationBrandingRead.

Use the Organization Branding workflow to manage brand name, slogan, colors, logo, and banner for one organization.

Legacy user-owned locations, organizations without configured branding, or actors without branding read access may render with an empty or partial branding object, so templates should keep fallbacks.

Collaboration

Use POST /v1/reports/{reportId}/collaboration/bootstrap to open the existing collaboration flow for a report draft.

Collaboration edits the report JSON draft directly. If the report was created without contentJson, the initial draft comes from the selected template's contentTemplateJson.

The normal publish action does not apply to report drafts. Generate the PDF from the report instead.

PDF Output

Call POST /v1/reports/{reportId}/generate-pdf when the report is ready.

The response gives you a job id. Poll GET /v1/reports/jobs/{jobId} until the job finishes.

When the job succeeds, the generated PDF is added to the location document library and becomes the latest generated PDF for that report.

Generation is a requester-attributed durable task. PixService records the actor and current entitlement/policy fingerprint at scheduling, reserves the Document destination, then rechecks the live requester, report, template, source images, destination path, and actual output size immediately before publication. A task that loses authority ends as AuthorizationChanged; a task that loses capacity ends as CapacityChanged.

Job status and report responses include generated-document metadata only while the polling actor can currently read that Document. A successful task can therefore remain successful while its document id, filename, size, and download URL are omitted after access changes.

The current API does not provide recurring report schedules, recipient delivery, or a separate rendered-output cache. LatestGeneratedDocumentId points to the latest ordinary location Document, which is re-authorized whenever it is returned.

ZIP export is not part of the current workflow.

Organization Branding

Manage reusable organization branding such as brand name, slogan, logo, banner, and colors.

Location Cameras

Pair cameras, upload periodic JPEG captures, and manage location-scoped image history.

On this page

Render a complete client documentOverviewWorkflowAccess requirementsTemplate ModelImage InputsBranding VariablesCollaborationPDF Output