Documentation

How PROMIVO works

The concepts you need to deploy an agent, build a workflow, and call the platform from your own systems.

Agents and versions

An agent is a catalogue listing plus one or more immutable versions. A version carries the system prompt, model configuration, the tools it may call, its input and output schemas, execution limits, and its automatic risk ceiling.

Publishing an update creates a new version and moves the current pointer. An existing version is never modified, so a run already in flight keeps the behaviour it started with.

Permissions and risk

Every tool declares a risk tier. An agent version declares the highest tier it may perform without a human.

READFetch, search, summarise. Changes nothing.
WRITESend an email, post an update, upsert a record.
DESTRUCTIVEDelete data or spend money.

A tool call above the ceiling is refused, recorded as a task awaiting approval, and reported back to the model as not performed. The run continues; the side effect does not happen.

Workflow nodes

Node	What it does
`TRIGGER`	Entry point. Manual, webhook, schedule or event.
`AI`	Runs an agent with an interpolated input template.
`HTTP`	Calls a public HTTP endpoint. Private ranges are blocked.
`CONDITION`	Branches on a value in the run context.
`TRANSFORM`	Reshapes data into a new object.
`EMAIL`	Sends an email through the configured provider.
`WEBHOOK`	POSTs a signed JSON payload outbound.
`DELAY`	Waits up to 300 seconds inside a run.
`DATABASE`	Records a note or reads recent executions.
`OUTPUT`	Defines the final result of the workflow.

Templating

Node configuration interpolates values from the run context. There is no expression evaluation, so a template can never execute code.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

Public API

Create a scoped key on the API keys page. The secret is shown once; only its hash is stored.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

Every response uses the same envelope:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

Endpoints

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Webhook triggers

A webhook workflow gets a public token and a signing secret shown once at creation. Sign the raw body with the secret.

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }