Jobs API

Version applicability

This page documents API in kis.ai release 2.0.0. The service’s runtime HTTP paths are unversioned — a /1.1.7/ documentation URL does not imply a /v1/ segment on the API itself.

Before you call

Tenancy headers, bearer authentication, the error envelope and the health probes are the same across every kis.ai service — see API conventions. This page documents what is specific to this block.

GET /jobs                    jobs defined for this product
GET /runs                    run history
GET /agents                  connected agents and their state
GET /workflow/queue          queued work
GET /workflow/queue/{id}     one queued item

Required headers

The platform tenancy headers apply — X-Kis-Tenant, X-Kis-Product, X-Kis-Environment.

Runs

GET /runs returns run history. A run carries its outcome and its logs, which is what makes “why did last night’s job fail” a query rather than an archaeology exercise across agent hosts.

Retry is by run id, and it re-dispatches the same job with the same input rather than re-deriving it — which matters when the trigger was a one-off webhook you cannot replay.

What a job dispatch carries

When the orchestrator hands work to an agent, the payload is:

Field	Notes
JobName	The job being run
RunID	This execution
Language	Script language for the job body
Code	The job body
Environment	Environment map available to the run
Capabilities	What this job is permitted to do
Constraints	Placement constraints for agent selection
Context	Trigger context — the webhook body, the changed row, the commit
Namespaces	Script namespaces the job may use; unset means defaults

Namespaces is the field worth being deliberate about. It is the sandbox boundary for the job body, the same way it is for any script — a job that only needs http should not be handed vault.

Context is how trigger data reaches the job: a webhook trigger puts the request body here, a database trigger the changed row, a git-poll trigger the commit.

The response

Field	Notes
JobName, RunID	Identify the run
Status	Outcome
Logs	Captured output

Agents

GET /agents lists connected agents and their state. Throughput is a function of how many are connected, so a silent drop here is capacity you believe you have and do not — see Operations.

Errors

The platform’s structured error body: a stable code, a message, and the request id.

Status	Meaning
400	Malformed request
401 / 403	Authentication or authorisation failure
404	Unknown job or run for this tenant
5xx	Dispatch failure

See also

• Usage — triggers, runs and retries
• Operations — capacity and failure modes

Authentication

Every route requires a bearer token:

Authorization: Bearer <token>

The health and readiness probes are the only unauthenticated surface.

Tenancy

The four CPET headers — X-Customer, X-Product, X-Env, X-Tenant — scope every job, run and queue entry. A request that cannot resolve a tenant is rejected rather than served against a default.

Errors

Status	Meaning
400	Request parse or validation failure
401	Missing or invalid token, as plain text
404	No such job, run or queue entry
500	Unexpected server error

400 and 500 carry the standard envelope; 401 does not.