Agent API Reference

Paijan Agent API

Deploy autonomous agents, feed them sensors, and let them act — inside guardrails you control.

Overview

An agent runs a loop: perceive a world-model from its sensors, reason a plan, then act through tools and actuators. You define the goal, the sensors and the guardrails. Base URL:

BASE https://api.paijan.dev

Authentication

Each agent key is scoped to a set of sensors and actions with a hard action budget.

Authorization: Bearer pj-agent-***

Actions outside a key's scope return 403 out_of_scope. Nothing actuates beyond its guardrails.

Deploy an agent

POST /v1/agents

# give it a goal, sensors and guardrails
curl https://api.paijan.dev/v1/agents \
  -H "Authorization: Bearer pj-agent-***" \
  -d '{ "goal":"monitor line A and flag anomalies",
       "sensors":["cam-A","telemetry-A"],
       "guardrails":{ "maxActions": 50, "canActuate": false } }'

Agents

Field	Type	Description
goal	`string`	Natural-language objective the agent pursues.
sensors	`string[]`	Sensor and API adapters the agent may perceive.
guardrails	`object`	Action budget, scope, and whether the agent may actuate.
region	`string`	Edge region to run the perception loop, e.g. `"sea"`.

Perceive

GET /v1/agents/:id/world

Returns the agent's current fused world-model — objects, telemetry and confidence.

{ "objects":[{"id":"unit-7","state":"ok","conf":0.97}],
  "telemetry":{"temp":41.2,"rpm":1180},
  "ts":1720000000 }

Act

POST /v1/agents/:id/act

Requests an action. If it passes guardrails it fires; otherwise it is rejected with a reason.

Field	Type	Description
tool	`string`	Tool, actuator or workflow to invoke.
args	`object`	Arguments for the action.
dryRun	`bool`	Validate against guardrails without firing.

Event stream

event: perceive  // new world-model frame
event: reason    // plan + chosen action
event: act       // action fired + result
event: block     // action rejected by guardrail

Guardrails

Guardrails are evaluated before any action. Set scope, budgets and a kill switch per agent.

guardrails: {
  maxActions: 50,
  canActuate: false,
  allow: ["notify", "log"],
  killSwitch: "pj-kill-***"
}

Errors

Code	Meaning
401	`invalid_key` — bad agent bearer token.
403	`out_of_scope` — action outside guardrails.
409	`budget_exhausted` — action budget reached.
423	`kill_switch_active` — agent is halted.

// Illustrative demo. Endpoints do not resolve.