Folders API Overview

The Informer Folders API provides endpoints for organizing content into hierarchical folder structures. Folders can contain reports, datasets, datasources, jobs, queries, templates, assistants, and libraries. All routes are prefixed with /api.

Features

• Hierarchical Organization - Create nested folder structures
• Bulk Operations - Assign multiple entities to folders at once
• Bulk Updates - Add, update, and remove folders in a single transaction
• Content Types - Organize multiple entity types (reports, datasets, jobs, etc.)
• Search - Find folders by name

Authentication

All Folder API endpoints require authentication via session cookies or API tokens. Creating folders requires permission.folders.create.

Endpoints

GET /api/folders

Get a list of all folders with optional name search.

Authentication: Required (session)

Query Parameters:

Parameter	Type	Description
name	string	Filter folders by name (partial match)

Response:

{
  "_links": {
    "self": { "href": "/api/folders" }
  },
  "_embedded": {
    "inf:folder": [
      {
        "id": "folder-123",
        "name": "Sales Reports",
        "parentId": null,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "_links": {
          "self": { "href": "/api/folders/folder-123" }
        }
      },
      {
        "id": "folder-456",
        "name": "Q1 2024",
        "parentId": "folder-123",
        "createdAt": "2024-01-14T14:22:00Z",
        "updatedAt": "2024-01-14T14:22:00Z",
        "_links": {
          "self": { "href": "/api/folders/folder-456" },
          "inf:parent-folder": { "href": "/api/folders/folder-123" }
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

---

POST /api/folders

Create a new folder.

Authentication: Required (session)

Pre-blocks: permission.folders.create

Request Body:

Field	Type	Required	Description
name	string	Yes	Folder name
parentId	string | null	No	Parent folder ID (null for root folder)

Example Request:

{
  "name": "Marketing Reports",
  "parentId": null
}

Response:

Returns the created folder object with 201 Created status and Location header.

{
  "id": "folder-789",
  "name": "Marketing Reports",
  "parentId": null,
  "createdAt": "2024-01-15T14:22:00Z",
  "updatedAt": "2024-01-15T14:22:00Z",
  "_links": {
    "self": { "href": "/api/folders/folder-789" }
  }
}

---

GET /api/folders/{id}

Get a specific folder by ID.

Authentication: Required (session)

Response:

{
  "id": "folder-123",
  "name": "Sales Reports",
  "parentId": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/folders/folder-123" },
    "inf:permissions": { "href": "/api/folders/folder-123/permissions" }
  }
}

---

PUT /api/folders/{id}

Update a folder's name or parent.

Authentication: Required (session)

Request Body:

Field	Type	Description
name	string	New folder name
parentId	string | null	New parent folder ID

Example Request:

{
  "name": "Sales & Marketing Reports",
  "parentId": "folder-parent"
}

Response:

Returns the updated folder object.

---

DELETE /api/folders/{id}

Delete a folder and all its subfolders.

Authentication: Required (session)

Response:

Returns 204 No Content on successful deletion.

Side Effects:

• Deletes all child folders recursively
• Does not delete entities in the folder (they become un-foldered)

---

GET /api/folders/{id}/subfolders

Get all direct subfolders of a folder.

Authentication: Required (session)

Response:

{
  "_links": {
    "self": { "href": "/api/folders/{id}/subfolders" }
  },
  "_embedded": {
    "inf:folder": [
      {
        "id": "folder-456",
        "name": "Q1 2024",
        "parentId": "folder-123"
      },
      {
        "id": "folder-457",
        "name": "Q2 2024",
        "parentId": "folder-123"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

---

GET /api/folders/{id}/permissions

Get permissions for a folder.

Authentication: Required (session)

Response:

Returns folder permissions object.

---

POST /api/folders/_bulk-assign

Assign multiple entities to a folder.

Authentication: Required (session)

Request Body:

Field	Type	Description
entities	array	Array of entity IDs (UUIDs) to assign
folderId	string | null	Folder ID to assign entities to (null to remove from folders)

Example Request:

{
  "entities": [
    "report-123",
    "dataset-456",
    "job-789"
  ],
  "folderId": "folder-123"
}

Response:

Returns success (no content).

Permission Checks:

• User must have write permission on each entity
• Entities without write permission are silently skipped
• Supports: reports, datasets, datasources, jobs, queries, templates, assistants, libraries

---

POST /api/folders/_bulk-update

Bulk add, update, and remove folders in a single transaction.

Authentication: Required (session)

Pre-blocks: permission.folders.create

Request Body:

Field	Type	Description
add	array	Folders to create
remove	array	Folder IDs to delete
update	array	Folders to update

Add Array Items:

Field	Type	Description
id	string	Folder ID (client-generated UUID)
name	string	Folder name
parentId	string | null	Parent folder ID

Update Array Items:

Field	Type	Description
id	string	Folder ID (UUID)
name	string	New folder name
parentId	string | null	New parent folder ID

Example Request:

{
  "add": [
    {
      "id": "new-folder-1",
      "name": "2024 Reports",
      "parentId": null
    }
  ],
  "remove": [
    "old-folder-123"
  ],
  "update": [
    {
      "id": "folder-456",
      "name": "Updated Name",
      "parentId": "new-parent"
    }
  ]
}

Response:

Returns success (no content).

Processing Order:

1. Remove folders (and their children)
2. Add new folders
3. Update existing folders

---

Folder Hierarchy

Folders support unlimited nesting depth:

Root
├── Sales Reports (folder-123)
│   ├── Q1 2024 (folder-456)
│   │   ├── January (folder-789)
│   │   └── February (folder-790)
│   └── Q2 2024 (folder-457)
└── Marketing Reports (folder-124)

Supported Entity Types

Folders can contain:

• Reports - Report definitions
• Datasets - Dataset configurations
• Datasources - Data source connections
• Jobs - Scheduled jobs
• Queries - Saved queries
• Templates - Document templates
• Assistants - AI assistants
• Libraries - Document libraries

Use Cases

Organize by Department

Root
├── Engineering
├── Sales
└── Marketing

Organize by Time Period

Root
├── 2023
│   ├── Q1
│   ├── Q2
│   ├── Q3
│   └── Q4
└── 2024
    ├── Q1
    └── Q2

Organize by Project

Root
├── Project Alpha
│   ├── Reports
│   ├── Datasets
│   └── Jobs
└── Project Beta