Skip to main content
POST
Create an on-premise agent.

Authorizations

Authorization
string
header
required

Enter your JWT token

Body

application/json

The agent creation payload. name is required; each omitted setting takes its own default (2 parallel tasks, 10s pull, Information).

Request body for creating an on-premise agent.

name
string
required

Display name for the new agent. Required - declared non-nullable so RequiredPropertiesSchemaProcessor marks it required in the OpenAPI document and the generated client rejects an omitted name before the round-trip.

description
string | null

Optional description of the agent.

applicationSlug
string | null

Which on-premise agent application to create under. Only needed when more than one exists - the 409 OPA_APPLICATION_AMBIGUOUS response lists the candidate slugs in its details so this can be retried with one of them.

settings
object | null

Optional runtime settings. Each member defaults independently when omitted: 2 parallel tasks, 10s pull, Information.

Response

The newly created agent, including its token.

Response for agent creation. Carries the token so a caller can provision a box in one round-trip. The token is a live credential - callers who would rather not have it in shell history should read it later from GET /v1/opa-agents/{id}/token instead.

agentId
integer<int32>
required

Identifier of the agent.

status
string
required

Liveness of the agent: WaitingForConnection, Online, Offline or Disabled.

createdBy
string<uuid>
required

Identifier of the user who created the agent.

createdDate
string<date-time>
required

When the agent was created.

name
string | null

Display name of the agent.

description
string | null

Optional description of the agent.

version
string | null

Version the agent last self-reported. Null until it first connects.

lastSeenAt
string<date-time> | null

Last heartbeat received from the agent. Null when it has never connected.

updatedBy
string<uuid> | null

Identifier of the user who last updated the agent.

updatedDate
string<date-time> | null

When the agent was last updated.

settings
object

Runtime settings currently stored for the agent.

appliedToAgent
boolean | null

False when a settings write reached the database but not the agent, because the agent was Offline. Null on reads - only set by update responses.

dispatchedTaskIds
string[] | null

Cloud task identifiers dispatched to the live agent by a settings write. Empty when offline.

token
string

The newly minted agent token.