Updates a job's name and description. There's one wrinkle if the job is a global job (shared to other fleet members) and this installation isn't the master copy -- see below.

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. Get the job's id (by name or from the list).
  3. Send the new name/description.
  4. Only if the job is global and this isn't the master: confirm severing it from global tracking, and retry.

The call

PATCH /api/jobs/{jobId}/name-description?confirmSever={true|false}

confirmSever is optional, defaults to false.

Permission needed: Job.Edit on this job.

The global-job wrinkle

If this job isn't global, or this installation is the master, this call just works -- your edit becomes the new shared definition if it's the master copy. But if the job is global and this installation is a subscriber (not the master), changing the name or description would create a permanent local divergence from the shared definition. So the first attempt (without confirmSever) is refused with a 409 telling you that; if you actually want to detach this copy and edit it locally, retry the exact same call with confirmSever=true.

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: Get the job's id by name.
var jobName = Uri.EscapeDataString("Nightly ETL Load");
var job = await (await client.GetAsync($"/api/jobs/by-name/{jobName}")).Content.ReadFromJsonAsync<JobRef>(jsonOptions);

// Step 3: Send the new name/description.
var edit = new RenameRequest(JobName: "Nightly ETL Load (v2)", Description: "Loads the warehouse tables from the OLTP source, now with retries.");
var response = await client.PatchAsJsonAsync($"/api/jobs/{job!.JobID}/name-description", edit, jsonOptions);

// Step 4: Only hit if it's a global job on a non-master installation.
if (response.StatusCode == System.Net.HttpStatusCode.Conflict)
{
    Console.WriteLine("This is a global job managed elsewhere. Retrying with confirmSever=true to detach it locally.");
    response = await client.PatchAsJsonAsync($"/api/jobs/{job.JobID}/name-description?confirmSever=true", edit, jsonOptions);
}

response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record JobRef(int JobID);
record RenameRequest(string JobName, string? Description);

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: Get the job's id by name. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$jobName = [Uri]::EscapeDataString("Nightly ETL Load")
$job = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/by-name/$jobName" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

# Step 3: Send the new name/description.
$body = @{ JobName = "Nightly ETL Load (v2)"; Description = "Loads the warehouse tables from the OLTP source, now with retries." } | ConvertTo-Json
try {
    Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$($job.jobID)/name-description" `
        -Method Patch -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
    "Updated."
}
catch [Microsoft.PowerShell.Commands.HttpResponseException] {
    # Step 4: Only hit if it's a global job on a non-master installation.
    if ($_.Exception.Response.StatusCode -eq 409) {
        Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$($job.jobID)/name-description?confirmSever=true" `
            -Method Patch -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
        "Updated (detached from global tracking)."
    } else {
        throw
    }
}

What you get back

204 No Content on success -- no body.

Codes this call can return

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

  • 204 -- updated.
  • 403 -- you don't have Job.Edit on this job.
  • 404 -- no job exists with that id.
  • 409 -- this is a global job, this installation isn't the master, and confirmSever wasn't passed as true. Body: { "requiresSever": true, "message": "..." }.

See also: Get a Job.