Skip to main content

Report API Overview

The Informer Report API provides comprehensive endpoints for creating, managing, and publishing reports. Reports are data visualizations and formatted outputs that can reference multiple datasets, include inputs for user parameters, and be shared across teams. All routes are prefixed with /api.

Features​

  • CRUD Operations - Create, read, update, and delete reports
  • Report Types - Support for multiple report drivers (standard, magic, dashboard, etc.)
  • Dataset References - Associate multiple datasets with configurable filters and snapshots
  • Draft Workflow - Create draft copies for safe editing without affecting production
  • Visual Templates - Manage charts, tables, and other visual components
  • Input Management - Define user input parameters and filters
  • Run Operations - Execute reports with parameters to generate output
  • Cloud Publishing - Publish reports to cloud with public links
  • Templates - Apply pre-built report templates
  • Sharing & Permissions - Team-based access control
  • Comments - Report discussions and annotations
  • Tags - Organize reports with metadata

Report Structure​

A report consists of:

ComponentDescription
TypeReport driver (standard, magicReport, etc.)
Name & DescriptionHuman-readable metadata
DefinitionJSONB structure containing visuals, layout, and configuration
Dataset ReferencesArray of datasets with aliases, filters, and snapshot settings
TemplateOptional template for layout and styling
SettingsUser-specific view preferences and defaults
OwnerUser or team that owns the report

Authentication​

All Report API endpoints require authentication via session cookies or API tokens. Most endpoints verify report permissions before allowing access.

Common Permission Patterns​

  • Read access - View report structure and metadata
  • Write permission - Required for report:write (create, update, delete, dataset management)
  • Copy permission - Required for report:copy (duplicate reports)
  • Cloud publish permission - Required for report:cloudPublish (publish to cloud)

Report Types​

Reports are powered by drivers that define their behavior:

TypeDescription
standardTraditional report with visuals and datasets
magicReportAI-powered report with dynamic content
dashboardMulti-visual dashboard layout
adhocQuick query-based report

Use GET /api/report-types to discover available drivers.

Drafts & Versioning​

Reports support draft mode for safe editing:

  1. Create draft - POST /api/reports/\{id\}/_edit
  2. Modify draft - Make changes without affecting production
  3. Commit draft - POST /api/reports/\{id\}/draft/_commit to publish changes
  4. Discard draft - DELETE /api/reports/\{id\}/draft to cancel

Dataset References​

Reports can reference multiple datasets with:

  • Alias - Unique identifier within the report
  • Label - Display name for the dataset
  • Filter - Applied criteria to limit data
  • Chips - Filter UI components
  • Snapshot Settings - Include historical dataset snapshots

Common Query Parameters​

Many list endpoints support:

ParameterTypeDefaultDescription
qstring-Full-text search query
sortstringnameSort field (prefix with - for descending)
startinteger0Pagination offset
limitinteger20Number of results per page

Error Responses​

Standard HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad request (validation error)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Resource not found
  • 409 - Conflict (duplicate, constraint violation)
  • 500 - Internal server error

Error responses include:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to modify report"
}

Next Steps​

Explore the specific endpoint categories: