Skip to main content

API Guide

We assume that everything has been set up correctly at this point.

The operator communicates with two main APIs:

  • the Guardrail Prover API — described by prover-openapi.json, accessible via Swagger UI at /swagger-ui and the guardrail-prover CLI
  • the Guardrail Verifier API — described by verifier-openapi.json, accessible via Swagger UI at /swagger-ui and the guardrail-verifier CLI
TODO

Instead of openapi filenames put links to rendered swagger UI.

Guardrail Prover API​

The prover is the main API for submitting data: templates, intents, and proposals. It does the heavy lifting of evaluating templates and generating proofs. Internally, it associates each intent with one of three states:

  • success — template evaluation and proof creation succeeded; the intent may be executed
  • failure — the proposal does not satisfy the intent, or proof creation failed
  • expiry — no proposal was submitted for the intent within its time-to-live (TTL, default: 24 h)

The API is organized into 3 endpoint groups:

Intents​

Submit and retrieve signed user intents:

  • POST /intents — Submit a signed intent
  • GET /intents/{intent_id} — Get a stored intent by its ID

Proposals​

Submit agent proposals for open intents:

  • POST /proposals — Submit a proposal for a pending intent, triggering the guardrail pipeline

Templates​

Upload and delete compiled templates:

  • POST /templates — Compile and store a template from its source
  • DELETE /templates/{template_id} — Delete a stored template by its ID

Guardrail Verifier API​

The verifier is the API for reading the outcome of the proving pipeline. It ingests events from the prover, verifies that the proofs are correct, and emits the same final states for each intent: success (proven and verified), failure, or expiry.

The API is organized into 2 endpoint groups:

Intents​

Query the status of intents:

  • GET /intents/{intent_id} — Get the current status of an intent

Proofs​

Fetch proof data:

  • GET /proofs/{intent_id} — Get the proof for an intent, if proving succeeded

Usage​

In technical terms, the operator connects to the Guardrail Prover API to:

  • configure templates and evidence extraction
  • submit intents (forwarding them from end-users or letting end-users post them directly)
  • submit proposals (forwarding them from agents or letting agents post them directly)

The operator connects to the Guardrail Verifier API to listen and query for the intent events that indicate the outcome for each intent.

CLI examples elsewhere in this guide use the guardrail-prover and guardrail-verifier CLIs for illustration, but any client that follows the OpenAPI specs works; auto-generated clients (e.g. via openapi-generator) or plain HTTP calls.

The server URLs are provided by Delta upon onboarding. Set them once, the CLIs will pick them up.

export GUARDRAIL_PROVER_URL=<prover_url>
export GUARDRAIL_VERIFIER_URL=<verifier_url>