Integration Guide

Guardrails is a drop-in proxy. Your existing AI code doesn't change — you add one URL and three headers.

Let your AI assistant install it

Using Claude, ChatGPT, Cursor, or Copilot? Paste this prompt and replace the two keys — the assistant finds the right file and makes the change:

Find where this project creates its Anthropic or OpenAI client.
Add a baseURL option pointing to https://aegisguardrails.com/anthropic
(or /openai for OpenAI) and add these default headers:
  X-Audit-Key: <my Guardrails key>
  X-Provider-Key: <my existing AI key>
Don't change anything else.

1. Get your API key

Sign up at aegisguardrails.com/signup. Your GUARDRAILS_API_KEY will be shown in your dashboard.

2. Update your client

// Anthropic
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: 'https://aegisguardrails.com/anthropic',
  defaultHeaders: {
    'X-Audit-Key':    process.env.GUARDRAILS_API_KEY,
    'X-Provider-Key': process.env.ANTHROPIC_API_KEY,
    'X-Actor-Id':     getCurrentUserId(),     // optional
    'X-Session-Id':   getSessionId(),         // optional
  },
})

// OpenAI
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://aegisguardrails.com/openai',
  defaultHeaders: {
    'X-Audit-Key':    process.env.GUARDRAILS_API_KEY,
    'X-Provider-Key': process.env.OPENAI_API_KEY,
  },
})

3. Read the audit metadata

Every response includes a _audit field:

const response = await client.messages.create({ ... })
console.log(response._audit)
// {
//   event_id: 'a3f8b21c-...',
//   hash: '3a7bd3e2...',
//   ledger_status: 'pending'  // → 'committed' after ~30s
// }

Fail-open guarantee

Guardrails sits in the path of every AI call you make, so the first question worth asking is: what happens if Guardrails itself has a problem? The answer is fail open — your AI call is never blocked by an audit-layer failure.

Internally, each call has two stages: forwarding the request to your AI provider, then fingerprinting, signing, and storing the audit record. Those stages fail differently, and we handle them differently:

• The AI provider itself errors or times out — there is no response to return, so we relay the provider's real error and status code back to you, unchanged.
• Our audit pipeline fails (a database outage, for example) after we already have a response from the provider — we still return that response to you. Nothing about your application's AI functionality depends on our audit infrastructure being healthy.

When the audit pipeline is the part that failed, the _audit field tells you so instead of silently going missing:

// Audit pipeline failure — your AI response is still returned in full
{
  ...,             // your normal AI response, unaffected
  "_audit": {
    "event_id": null,
    "hash": null,
    "ledger_status": "audit_failed",
    "warning": "Guardrails could not record this call due to an internal error.
                 Your AI response was still returned. This call is not covered
                 by your audit trail."
  }
}

We recommend checking _audit.ledger_status for "audit_failed"if you want to alert on gaps in your audit coverage — but you never need to handle it defensively the way you'd handle a real API error, because your application keeps working either way.

There is one failure mode this can't cover: if our service is fully unreachable (network partition, DNS issue), no request reaches us at all. For that case, the same one-line design that makes installation easy also makes a fallback easy — point your client at the provider directly on catch:

// Optional client-side fallback if Guardrails is unreachable
let response
try {
  response = await guardrailsClient.messages.create({ ... })
} catch (err) {
  if (isConnectionError(err)) {
    response = await directAnthropicClient.messages.create({ ... }) // unaudited fallback
  } else {
    throw err
  }
}

4. Verify a record

Any record can be publicly verified — no login required:

GET https://aegisguardrails.com/verify/{event_id}

// Response
{
  "eventId": "a3f8b21c-...",
  "hash": "3a7bd3e2...",
  "platformSigValid": true,
  "customerSigValid": true,
  "onChain": true,
  "blockHeight": 41823,
  "tampered": false
}

5. Signing key — bring your own key (BYOK)

Every record is already signed by our platform key. For a second, independent signature that neither side can forge alone, generate a signing key pair in your console under Settings → Signing Key. The private key is generated in your browser, downloaded straight to your machine, and never sent to us — only the public key is registered with your account.

After a proxied call, you already have _audit.hash. Sign that hash with your private key (P-256 / ECDSA, SHA-256, IEEE-P1363 signature encoding) and submit it back — this is meant to run in your own backend, not the browser:

import { createSign, createPrivateKey } from 'crypto'

// privateKeyJwk is the JSON file downloaded when you generated your signing key
const key = createPrivateKey({ key: privateKeyJwk, format: 'jwk' })

const sign = createSign('SHA256')
sign.update(Buffer.from(response._audit.hash, 'hex'))
sign.end()
const signature = sign.sign({ key, dsaEncoding: 'ieee-p1363' }).toString('hex')

await fetch(`https://aegisguardrails.com/events/${response._audit.event_id}/cosign`, {
  method: 'POST',
  headers: { 'X-Audit-Key': process.env.GUARDRAILS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ signature }),
})

Once submitted, GET /verify/{event_id} reports customerSigValid: true alongside the platform signature — a regulator can confirm both independently, without ever needing your private key.

6. Aegis Verify — anchor any hash, no AI call required

Everything above audits AI calls specifically. If you just need to anchor a hash you've already computed — a contract revision, a decision log entry, an export of records — POST /anchorseals it on the same Verilink'ed ledger, Merkle-batched and publicly verifiable exactly like an AI call:

POST https://aegisguardrails.com/anchor
X-Audit-Key: <your Guardrails key>
Content-Type: application/json

{ "hash": "3a7bd3e2...", "label": "contract-v4-signed" }

// Response
{ "event_id": "a3f8b21c-...", "hash": "3a7bd3e2...", "ledger_status": "pending" }

The same GET /verify/{event_id} endpoint verifies it. This is the basis of Aegis Verify — useful anywhere you need a tamper-proof timestamp on something, independent of any AI provider.

7. Alerts — webhook / Slack

Set a webhook URL in the console under Settings → Alerts to get notified when usage crosses 50/80/100% of your plan, or when a call's audit record couldn't be saved. Any Slack incoming-webhook URL works directly — the payload includes a top-level text field, which is all Slack reads:

{
  "text": "Guardrails: you've used 80% of your plan's monthly call limit (40,000/50,000).",
  "event": "usage_threshold",
  "pct": 80
}

Headers reference