Reports API

The Reports module exposes a comprehensive REST API under the /api/reports/ prefix, allowing you to automate all operations available through the graphical interface: creating and managing templates, generating PDFs, viewing history, customizing branding, creating custom Python blocks, and configuring matrix rules. This page documents the twenty-three available endpoints along with their input and output schemas.

Endpoints Overview

Endpoints are grouped into seven functional families. Each family corresponds to a specific area of the interface and can be used independently.

Templates

The five template endpoints form a complete CRUD suite. Default (embedded) templates are read-only; modifications only apply to user-created templates.

Creation Schema (TemplateCreate): name, blocks (list of keys), description, language (default 'fr'), mode ('concis' or 'expert'). Update (TemplateUpdate) only accepts blocks, name, and description.

Generation

Two endpoints share the same internal logic. The only difference is that /preview forces the is_preview=True flag, producing a temporary, non-persisted PDF intended for viewing in a new tab.

ReportGenerateRequest Schema

The generation input schema is the most detailed in the API. It includes sixteen optional fields covering report structure, data inclusion, and environmental context.

Retrieval and Download

Generated reports are persisted on the server with an ID and a PDF file path. The API allows listing, retrieving metadata, downloading the file, and deletion.

Nexus Sessions

A dedicated endpoint lists available Nexus sessions to populate the report creation form. It reads directly from the SQLite sessions database and returns the fifty most recent entries.

Each returned session contains its ID, name, associated sample_id and sample_name, the processed element, and the creation date. This information is used to provide a dropdown menu for the user in the interface.

Branding

Branding includes the organization name and the path to a local logo that will be injected into report headers and footers. It is stored on the server and applied automatically during each generation.

The update validates that the provided logo path points to an existing file and that its extension is recognized (PNG, JPG, JPEG, or SVG). A missing file or unsupported format returns a 400 error with an explicit message.

Custom Blocks

The five custom block endpoints form a full CRUD suite with one key feature: backend Python syntax validation before acceptance.

The CustomBlockCreate schema requires: key, name, and code_python. Other fields have default values: description='', category='custom', nature='I', icon='CB', licence='pro', expert=False, language='fr', api_calls=None.

Groups and Matrix Rules

Sampling matrices (water, soil, sediment, etc.) can be grouped by affinity, and relevance rules can be defined between these groups. This configuration supports validations performed when comparing different matrices within the same report.

A matrix group includes an ID, name, color, a list of concrete matrices, and an optional note. A rule links two groups (from_group, to_group), carries a relevant flag (boolean), and a note. The check endpoint returns relevant (bool or null) and defined (bool indicating if the rule exists).

Standard Error Codes

All endpoints follow the same HTTP error code conventions.

Programmatic Usage Example

The following example illustrates a complete workflow in Python using the requests library: selecting a Nexus session, generating the report, and downloading the PDF.

import requests

base = 'http://localhost:8000'

# Select a Nexus session
sessions = requests.get(f'{base}/api/reports/nexus-sessions').json()
session_id = sessions['sessions'][0]['id']

# Generate report with the expert preset
payload = {
    'blocks': ['cover_page', 'executive_summary', 'sample_inventory',
               'nexus_processes', 'nexus_chain', 'limitations',
               'certification'],
    'title': 'Automated Audit -- Nexus session',
    'nexus_session_id': session_id,
    'language': 'en',
}
resp = requests.post(f'{base}/api/reports/generate', json=payload)
report = resp.json()

# Download the PDF
pdf = requests.get(f'{base}/api/reports/download/{report["id"]}')
with open('report.pdf', 'wb') as f:
    f.write(pdf.content)

This automation is the recommended path for integrating IsoFind into larger pipelines: continuous monitoring, periodic follow-up reports, or batch production of certifications for a portfolio of sites.

Authentication

The API is protected by the same authentication system as the graphical interface. A token is required in the HTTP header for endpoints that modify state or access sensitive data. Read-only endpoints for default templates are accessible without a token.

Details on obtaining and using the token are described in the general IsoFind API documentation. For third-party integrations, a service token can be generated in the administration panel and revoked independently of the user account.

Going Further

• Generate a Report: Equivalent workflow via the UI.
• Custom Blocks: Full schema and constraints for custom blocks.
• IsoFind API: Authentication and endpoints for other modules.
• Python Integration: Using the isof client package.