Creates a new folder, optionally nested under a parent and optionally tagged at creation. There's no rename, move, or delete for a folder anywhere in the API today -- once created, a folder's own name and parent can only be changed directly in the database. (Jobs can still be moved into or out of a folder -- that's a job-level operation, not a folder one.)

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

  1. Authenticate to the API.
  2. Send the new folder's details.

The call

POST /api/folders

Permission needed: Job.Edit, scoped to the parent folder (ParentFolderId) -- or unscoped if creating at the root (ParentFolderId: null).

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: Send the new folder's details.
var newFolder = new CreateFolderRequest(FolderName: "Weekly Reports", ParentFolderId: 3, Tags: new List<string> { "reporting" });
var response = await client.PostAsJsonAsync("/api/folders", newFolder, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedFolder>(jsonOptions);
Console.WriteLine($"Created folder id: {created!.FolderID}");

record CreateFolderRequest(string FolderName, int? ParentFolderId, List<string>? Tags);
record CreatedFolder(int FolderID);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: Send the new folder's details. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newFolder = @{ FolderName = "Weekly Reports"; ParentFolderId = 3; Tags = @("reporting") } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/folders" `
    -Method Post -Body $newFolder -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Created folder id: $($created.folderID)"

What you get back

201 Created:

{ "FolderID": 12 }

Any tag names in Tags that don't already exist are created automatically (with the default color) -- there's no separate "create a tag" call needed first.

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

  • 201 -- created.
  • 403 -- you don't have Job.Edit on the parent folder.

A duplicate folder name isn't specially handled -- it isn't checked for in this endpoint.

See also: List Folders, Move a Job to a Folder.