Reports

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 the current user or accessible organizations.
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.

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.

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

User-owned locations or organizations without configured branding may still 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.

ZIP export is not part of the current workflow.