HTTP Reference Guide

HTTP Reference

This page is the reference for the two parts of the local HTTPS API that integrators use: the Plugin Settings API, called from inside a running job task or plugin to read runtime configuration, and the Job Management API, called by deployment tooling to create, update, and trigger jobs.

The Custom Job Integration Guide covers when and why to call each endpoint. The Custom Plugin Integration Guide covers Plugin Settings for managed plugins. This page is what you reach for when scripting a deployment or checking an endpoint signature.

Base URL and TLS

The agent exposes its API on the loopback interface only. There is no remote access.

Setting

Typical value

Source

HTTPS port	6889	Settings:KestrelHttpsPort in appsettings.json
HTTP port	6888	Settings:KestrelHttpPort in appsettings.json
TLS certificate	Self-signed, locally generated	Confirm with your administrator; use your org's CA bundle if provided

Use HTTPS for all API calls. The base URL is:

https://127.0.0.1:{KestrelHttpsPort}

The agent uses a self-signed TLS certificate on many installs. HTTP clients connecting from loopback must either trust that certificate explicitly (via a CA bundle your administrator exports) or disable certificate verification for loopback connections per your security policy. Do not use the HTTP port for sensitive operations — prefer HTTPS.

Confirm actual port values with your deployment team before hardcoding them. Use {KeeperApiBaseUrl} argument substitution in your job task to receive the correct base URL at runtime rather than hardcoding 127.0.0.1:6889.

Authorization Tiers

Every request is classified by the agent's authorization middleware into a required tier. The two tiers integrators interact with are:

Tier

Who can call it

What it covers

Admin	Deployment tooling authenticated with admin-class credentials — typically mutual TLS with a client certificate provisioned by your Keeper deployment team	All job management endpoints: create, update, delete, validate, trigger, reload
Plugin	Processes the agent launched and registered as trusted — a job task started by the job runner, or a managed plugin started by the orchestrator	All Plugin Settings endpoints: read merged settings, read/write individual keys, revert

The key practical implication: these are two separate callers, not two modes for the same binary.

Your job task binary calls Plugin Settings (Plugin tier) from inside a running job. Your deployment scripts call the Job Management API (Admin tier) from outside — from a CI system, a workstation, or an automation tool provisioned with admin credentials. Do not attempt to call /api/Jobs from inside your task binary, and do not expect /api/PluginSettings/... to work from an arbitrary script or shell session.

If you receive 403 and TLS succeeded, the problem is the authorization tier — not the certificate or the network. Confirm which tier the endpoint requires and whether the calling process satisfies it.

Plugin Settings API

All endpoints under /api/PluginSettings require Plugin-tier authorization. The caller must be a process that the agent launched and registered — a job task or managed plugin. Manual invocations (running your binary from a shell, a CI runner, or a test script) will receive 403.

Endpoints

Method

Path

Request body

Response

GET	/api/PluginSettings/{pluginName}	—	200 — flat JSON object of string keys to string values (merged effective settings)
GET	/api/PluginSettings/{pluginName}/{settingName}	—	200 — single setting value
PUT	/api/PluginSettings/{pluginName}/{settingName}	PluginSettingValue JSON	200 on success
POST	/api/PluginSettings/{pluginName}/revert	—	200 — re-imports that plugin's on-disk JSON into unified storage
POST	/api/PluginSettings/revert-all	—	200 — re-imports all plugins from their on-disk JSON
GET	/api/PluginSettings/{pluginName}/status	—	Configuration change and hash status

{pluginName} Values

Use KeeperPrivilegeManager as the plugin name to read system-wide merged settings, including broker.host and broker.port. This is the standard call for any job task that needs the MQTT broker address.

Use your own plugin's id (for example MyBridge) to read or write settings scoped to that plugin specifically.

Response Shape for GET /api/PluginSettings/{pluginName}

The response is a flat JSON object where every value is a string:

{
  "broker.host": "127.0.0.1",
  "broker.port": "8675",
  "some.other.key": "value"
}

Parse only the keys your integration needs. Other keys may be present depending on the agent version and policy configuration.

PUT Request body

To write a single setting:

{
  "value": "new-value-here"
}

Common Failures

Response

Cause

403	Process is not Plugin-authenticated — it was not started by the agent, or it has not yet been registered in the launched-process registry. Add a retry on startup if the failure occurs immediately after the process starts.
404	The plugin name does not exist in the agent's plugin registry. Confirm the plugin is deployed and the name matches exactly.

Job Management API

All endpoints under /api/Jobs require Admin-tier authorization unless noted. The exact authentication mechanism — client certificates, mutual TLS, or another admin credential — is deployment-specific. Your Keeper deployment team will provide the credentials and tooling for your environment.

Endpoints

Method

Path

Request body

Response

GET	/api/Jobs	—	200 — object with jobs array, count, and message
GET	/api/Jobs/{jobId}	—	200 — job definition JSON; 404 if not found
POST	/api/Jobs	Job JSON	200 on success; 400 with validation errors if invalid
PUT	/api/Jobs/{jobId}	Job JSON	200 on success; 404 if job does not exist
DELETE	/api/Jobs/{jobId}	—	200 on success; 404 if not found
POST	/api/Jobs/validate	Job JSON	200 — object with valid, errors, warnings, jobId; does not save
POST	/api/Jobs/{jobId}/trigger	Optional JSON object	200 — triggers a run with optional event context; 400 if job is disabled
POST	/api/Jobs/{jobId}/run	—	200 — triggers async execution; 400 if job is disabled
POST	/api/Jobs/reload	—	200 — reloads job definitions from disk

Notes on Specific Endpoints

POST /api/Jobs — Creates or updates a job. Runs the full job validator, which requires the task binary to exist on disk at the path specified in the job JSON at the time of the call. Deploy the binary before calling this endpoint. If the job's osFilter excludes the current OS, binary existence checks are skipped for that run.

POST /api/Jobs/validate — Identical validation to POST /api/Jobs but does not write anything. Use this to test a job JSON against a live agent before committing. The response body tells you whether the job is valid and lists any errors or warnings.

PUT /api/Jobs/{jobId} — The id in the URL is authoritative. If the job JSON body contains a different id, it is overwritten with the URL value.

POST /api/Jobs/{jobId}/trigger — The preferred way to run a job manually during testing. The optional request body can pass event context as a key-value JSON object. An empty body ({}) is also accepted.

POST /api/Jobs/reload — Forces the agent to re-read job definitions from the Jobs/ directory. Use after placing files on disk via a blessed path to pick up changes without restarting the agent.

{jobId} format

Job IDs are URL-encoded in path segments. Hyphens are allowed. Do not use underscores in job IDs — the MQTT broker splits client IDs on underscores to extract the job ID, and underscores in the ID break that parsing. See the Custom Job Integration Guide for details.

Common Failures

Response

Cause

400	Validation failed — binary not found on the validating host, malformed JSON, or a required field is missing. Check the errors array in the response body.
403	Admin credentials not provided or not accepted. Confirm with your deployment team that the client certificate or auth token is correct for this agent.
404	Job ID not found — either the job was never created or the ID does not match. Use GET /api/Jobs to list what exists.

Basic Examples

These examples use PowerShell and curl. Replace the certificate paths, URL, and JSON file with values for your environment.

Validate a Job Without Saving (PowerShell):

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/validate" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-job.json)

Create a Job (PowerShell):

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-job.json)

Trigger a Job Run Manually (PowerShell):

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/my-job-id/trigger" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body "{}"

List All Registered Jobs (curl):

curl -s https://127.0.0.1:6889/api/Jobs \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem

Create a Job (curl):

curl -s -X POST https://127.0.0.1:6889/api/Jobs \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem \
  -H "Content-Type: application/json" \
  -d @my-job.json

Delete a Job (curl):

curl -s -X DELETE https://127.0.0.1:6889/api/Jobs/my-job-id \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem