Core CRUD

Basic report creation, retrieval, update, and deletion operations.

GET /api/reports

Search and filter reports with pagination.

Authentication: Required

Query Parameters:

Parameter	Type	Default	Description
q	string	-	Full-text search query (searches name, slug, description)
sort	string	-	Sort field (prefix with - for descending)
limit	integer	20	Results per page
start	integer	0	Pagination offset

Response:

The response is a paginated HAL collection. Report items are returned under _embedded["inf:report"]. The search returns a limited set of attributes per report.

{
  "_links": {
    "self": { "href": "/api/reports{?sort,limit,start,q}", "templated": true },
    "next": { "href": "/api/reports?start=20&limit=20" }
  },
  "_embedded": {
    "inf:report": [
      {
        "_links": {
          "self": { "href": "/api/reports/analytics:sales-dashboard" }
        },
        "id": "d4f8a2b1-...",
        "type": "dashboard",
        "name": "Sales Dashboard",
        "slug": "sales-dashboard",
        "description": "Quarterly sales analysis dashboard",
        "ownerId": "analytics",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-02-08T14:30:00.000Z"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 48,
  "aggs": {
    "total": 48
  },
  "permissions": {
    "create": true
  }
}

Key Fields: Each embedded report includes only: id, type, name, ownerId, slug, description, createdAt, updatedAt. Use GET /api/reports/{id} for full details.

Use Case:

List all reports the authenticated user can access, with search and pagination support.

---

GET /api/reports-list

Get a complete list of readable reports with tags, sharing info, and related datasets/datasources.

Authentication: Required

Response:

Returns a plain JSON array of reports (plus ad hoc queries and templates) with additional metadata. Each item is enriched with dataset/datasource names, tags, sharing info, and permissions.

[
  {
    "id": "d4f8a2b1-...",
    "driver": "report",
    "type": "Dashboard",
    "originalType": "report",
    "name": "Sales Dashboard",
    "description": "Quarterly sales analysis dashboard",
    "slug": "sales-dashboard",
    "naturalId": "analytics:sales-dashboard",
    "ownerId": "analytics",
    "ownerName": "Analytics Team",
    "folderId": null,
    "shared": true,
    "favorite": false,
    "datasourceId": "a1b2c3d4-...",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-02-08T14:30:00.000Z",
    "datasets": ["Customer Data", "Orders"],
    "datasources": ["MySQL Production"],
    "tags": ["tag-uuid-1", "tag-uuid-2"],
    "icon": "ChartBar",
    "image": "/images/report-type.svg",
    "listId": "report:d4f8a2b1-...",
    "sharing": { "accessLevel": 2 },
    "rels": {
      "self": "inf:report",
      "owner": "inf:report-owner",
      "share": "inf:report-share",
      "tag": "inf:report-tag"
    },
    "permissions": {
      "write": true,
      "edit": true,
      "delete": true,
      "share": true,
      "copy": true,
      "assign-tags": true,
      "change-owner": true
    }
  }
]

Key Details:

• This endpoint returns reports, ad hoc queries, and templates combined (distinguished by driver field)
• type is a localized display name (e.g., "App", "Ad hoc Query")
• originalType preserves the raw driver type
• datasets and datasources are arrays of display names (not IDs)
• tags are arrays of tag UUIDs
• sharing reflects the current user's datasource access level
• rels provides HAL relation names for client-side link construction

Use Case:

Get enriched report list for UI display with all related metadata in a single request.

---

POST /api/reports

Create a new report.

Authentication: Required

Permissions: reports:create

Request Body:

{
  "type": "standard",
  "name": "Q1 Sales Report",
  "slug": "q1-sales-report",
  "ownerId": "team:analytics",
  "description": "First quarter sales analysis",
  "templateId": "template-id",
  "queryId": "query-id",
  "defn": {
    "visuals": [],
    "layout": {}
  },
  "datasets": {
    "orders": {
      "datasetId": "orders-2024",
      "alias": "orders",
      "label": "Orders Dataset",
      "filter": {},
      "chips": [],
      "snapshots": {
        "includeLatest": true,
        "type": "n",
        "n": 5,
        "snapshotDatasets": ["snapshot-id-1", "snapshot-id-2"]
      }
    }
  }
}

Required Fields:

Field	Type	Description
type	string	Report driver type (must be valid and eligible)

Optional Fields:

Field	Type	Description
name	string	Report name
slug	string	URL-safe identifier
description	string	Report description
ownerId	string	Owner (defaults to current user)
templateId	string	Template to apply
magicReportTemplateId	string	App template ID
queryId	string	Associated query ID
datasets	object	Dataset references (keys are aliases)

Response:

{
  "id": "team:q1-sales-report",
  "type": "standard",
  "name": "Q1 Sales Report",
  "ownerId": "team:analytics",
  "defn": {},
  "createdAt": "2024-02-09T10:00:00Z",
  "_links": {
    "self": { "href": "/api/reports/team:q1-sales-report" }
  }
}

Status Code: 201 Created

Location Header: URL of the created report

---

GET /api/reports/{id}

Get a specific report by ID.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID (natural ID format: ownerId:slug or UUID)

Response:

{
  "id": "team:sales-dashboard",
  "type": "dashboard",
  "name": "Sales Dashboard",
  "slug": "sales-dashboard",
  "description": "Quarterly sales analysis",
  "ownerId": "team:analytics",
  "defn": {
    "visuals": [
      {
        "id": "visual-1",
        "type": "chart",
        "name": "Revenue Trend",
        "component": {}
      }
    ]
  },
  "settings": {},
  "datasourceId": "mysql-prod",
  "queryId": null,
  "templateId": "template-123",
  "shared": true,
  "defnUpdatedAt": "2024-02-08T14:30:00Z",
  "enableFilter": true,
  "tags": ["sales", "dashboard"],
  "datasets": {
    "orders": {
      "alias": "orders",
      "datasetId": "orders-2024",
      "label": "Orders Dataset"
    }
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-02-08T14:30:00Z",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard" },
    "inf:owner": { "href": "/api/reports/team:sales-dashboard/owner" },
    "inf:draft": { "href": "/api/reports/team:sales-dashboard/draft" },
    "inf:report-datasets": { "href": "/api/reports/team:sales-dashboard/dataset-refs" },
    "inf:report-run": { "href": "/api/reports/team:sales-dashboard/_run" },
    "edit": { "href": "/api/reports/team:sales-dashboard/_edit" }
  },
  "_embedded": {
    "inf:datasource": {},
    "inf:template": {},
    "inf:query": {}
  }
}

HAL Links:

The response includes HAL links for related resources:

• inf:owner - Owner management
• inf:draft - Draft version
• inf:report-datasets - Dataset references
• inf:report-run - Execute report
• inf:comments - Report comments
• inf:report-shares - Sharing configuration
• edit - Create draft for editing (only if not already a draft)
• inf:copy - Copy report
• inf:cloud-publish - Publish to cloud
• view - View report in UI

---

PUT /api/reports/{id}

Update an existing report.

Authentication: Required

Permissions: report:write

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Request Body:

{
  "name": "Updated Sales Dashboard",
  "description": "Updated description",
  "defn": {
    "visuals": [
      {
        "id": "visual-1",
        "type": "chart",
        "name": "Revenue Trend",
        "component": {},
        "index": 0
      }
    ]
  },
  "datasets": {
    "orders": {
      "datasetId": "orders-2024",
      "alias": "orders",
      "label": "Orders Dataset",
      "filter": {}
    }
  }
}

Response:

Returns the updated report (same structure as GET).

Notes:

• When updating defn.visuals, only specific fields are preserved: id, component, name, defaultName, description, defaultDescription, type, contextId, and index
• The index field is automatically set based on array position
• New dataset references found in the definition are automatically created
• Existing dataset configurations in the datasets object are upserted

---

PATCH /api/reports/{id}

Apply JSON Patch operations to a report (use sparingly).

Authentication: Required

Permissions: report:write

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Request Body:

[
  { "op": "replace", "path": "/name", "value": "New Report Name" },
  { "op": "add", "path": "/defn/visuals/0", "value": {} }
]

Response:

Returns the patched report.

Warning:

This route should be avoided for nested structures. Use PUT instead. JSON Patch remove operations are converted to add with null value.

---

DELETE /api/reports/{id}

Delete a report.

Authentication: Required

Permissions: report:write

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

204 No Content on success.

---

GET /api/reports/{id}/owner

Get the owner of a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

{
  "ownerId": "team:analytics",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/owner" }
  }
}

---

PUT /api/reports/{id}/owner

Change the owner of a report.

Authentication: Required

Permissions: report:changeOwner

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Request Body:

{
  "ownerId": "user:john.doe"
}

Response:

{
  "ownerId": "user:john.doe",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/owner" }
  }
}

---

GET /api/report-types

Get all available report drivers.

Authentication: Required

Response:

{
  "_links": {
    "self": { "href": "/api/report-types" }
  },
  "_embedded": {
    "inf:report-type": [
      {
        "id": "standard",
        "name": "Standard Report",
        "description": "Traditional report with visuals and datasets"
      },
      {
        "id": "magicReport",
        "name": "App",
        "description": "AI-powered report with dynamic content"
      },
      {
        "id": "dashboard",
        "name": "Dashboard",
        "description": "Multi-visual dashboard layout"
      }
    ]
  },
  "start": 0,
  "count": 3,
  "total": 3
}

---

GET /api/report-types/{id}

Get a specific report driver by ID.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report type/driver ID

Response:

{
  "id": "standard",
  "name": "Standard Report",
  "description": "Traditional report with visuals and datasets",
  "capabilities": []
}