Creates a new job. This only creates the job's identity and a first (empty) draft version -- add steps to it separately.

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 job's details.

The call

POST /api/jobs

Permission needed: Job.Edit, scoped to the folder you're creating the job in (FolderId). Creating with IsGlobal: true also needs Job.ManageGlobal on that same folder.

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 job's details.
var newJob = new CreateJobRequest(
    JobName: "Weekly Report Export",
    Description: "Exports the weekly summary report to the shared folder.",
    FolderId: 3,
    ContactName: "Data Team",
    ContactEmail: "data-team@example.com",
    ContactPhone: null,
    Tags: new List<string> { "reporting" },
    IsGlobal: false);

var response = await client.PostAsJsonAsync("/api/jobs", newJob, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedJob>(jsonOptions);
Console.WriteLine($"Created job id: {created!.JobID}");

record CreateJobRequest(string JobName, string? Description, int? FolderId, string? ContactName,
    string? ContactEmail, string? ContactPhone, List<string>? Tags, bool IsGlobal = false);
record CreatedJob(int JobID);

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 job's details. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newJob = @{
    JobName      = "Weekly Report Export"
    Description  = "Exports the weekly summary report to the shared folder."
    FolderId     = 3
    ContactName  = "Data Team"
    ContactEmail = "data-team@example.com"
    Tags         = @("reporting")
    IsGlobal     = $false
} | ConvertTo-Json

$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs" `
    -Method Post -Body $newJob -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Created job id: $($created.jobID)"

What you get back

201 Created, with a Location header pointing at Get a Job for the new job, and body:

{ "JobID": 57 }

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 that folder (or Job.ManageGlobal, if IsGlobal was true).

A duplicate JobName isn't specially handled here -- it fails as a raw database error rather than a clean 409, so check List Jobs/Get a Job by Name first if you're not sure the name is free.

See also: Get a Job, Delete a Job.