API Reference

curl -X POST https://api.lakefrontai.com/events \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id":        "evt_001",
    "session_id":      "ses_abc123",
    "mandate_id":      "man_xyz789",
    "agent_id":        "agent_checkout_v2",
    "sequence_number": 1,
    "category":        "payment",
    "method":          "stripe.charge",
    "status":          "success",
    "initiated_at":    1718000000000,
    "data": {
      "amount":   4999,
      "currency": "usd",
      "customer": "cus_abc"
    }
  }'

curl -X POST https://api.lakefrontai.com/disputes/dsp_001/packet \
  -H "Authorization: Bearer lf_your_api_key"

Authorization: Bearer lf_your_api_key

curl -X POST https://api.lakefrontai.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "s3cret" }'

curl -X POST https://api.lakefrontai.com/events \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -H "x-attestation-token: at_abc..." \
  -d '{
    "event_id":        "evt_stripe_charge_001",
    "session_id":      "ses_user_42_checkout",
    "mandate_id":      "man_purchase_flow_v3",
    "agent_id":        "agent_checkout_v2",
    "sequence_number": 3,
    "category":        "payment",
    "method":          "stripe.charge",
    "status":          "success",
    "initiated_at":    1718000000000,
    "data": {
      "amount":      4999,
      "currency":    "usd",
      "customer_id": "cus_abc",
      "description": "Pro plan subscription"
    }
  }'

curl -X POST https://api.lakefrontai.com/events/batch \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "evt_001", "session_id": "ses_abc",
        "mandate_id": "man_xyz", "agent_id": "agent_v2",
        "sequence_number": 1, "category": "auth",
        "method": "stripe.customer.retrieve", "status": "success",
        "initiated_at": 1718000000000, "data": { "customer": "cus_abc" }
      },
      {
        "event_id": "evt_002", "session_id": "ses_abc",
        "mandate_id": "man_xyz", "agent_id": "agent_v2",
        "sequence_number": 2, "category": "payment",
        "method": "stripe.charge", "status": "success",
        "initiated_at": 1718000001000, "data": { "amount": 4999 }
      }
    ]
  }'

curl "https://api.lakefrontai.com/events?session_id=ses_abc&limit=20" \
  -H "Authorization: Bearer lf_your_api_key"

const es = new EventSource(
  "https://api.lakefrontai.com/events/stream",
  { headers: { Authorization: "Bearer lf_your_api_key" } }
);

es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(event.method, event.status);
};

curl "https://api.lakefrontai.com/events/export?session_id=ses_abc" \
  -H "Authorization: Bearer lf_your_api_key" \
  -o events.csv

curl -X POST https://api.lakefrontai.com/mandates \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":          "agent_checkout_v2",
    "display_name":      "Monthly subscription renewal bot",
    "authorized_scopes": ["payment", "data_read"],
    "spending_limit":    100000,
    "currency":          "USD",
    "expires_at":        "2027-01-01T00:00:00.000Z",
    "issued_by":         "admin@company.com",
    "notes":             "Authorized in board meeting 2026-06-01",
    "constraints": {
      "payment": {
        "max_amount_per_tx":   4999,
        "max_tx_per_day":      10,
        "allowed_currencies":  ["USD", "EUR"],
        "require_mfa":         false
      }
    }
  }'

curl "https://api.lakefrontai.com/mandates?state=active" \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/mandates/man_7f3a9c \
  -H "Authorization: Bearer lf_your_api_key"

curl -X PATCH https://api.lakefrontai.com/mandates/man_7f3a9c \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "spending_limit": 200000, "expires_at": "2027-06-01T00:00:00.000Z" }'

curl -X POST https://api.lakefrontai.com/mandates/man_7f3a9c/revoke \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "revoked_by": "admin@company.com", "reason": "Agent decommissioned" }'

{
  "payment": {
    "max_amount_per_tx":   4999,       // max single-tx amount in cents
    "max_tx_per_day":      10,          // velocity: transactions per day
    "max_tx_per_month":    50,          // velocity: transactions per month
    "cumulative_limit":    100000,      // lifetime cap in cents
    "allowed_currencies":  ["USD"],     // whitelist; omit for any
    "allowed_merchants":   ["stripe"],  // whitelist of method prefixes
    "require_mfa":         false        // block tx until consent confirmed
  },
  "refund": {
    "max_amount_per_tx":   4999,
    "max_tx_per_day":      5
  }
}

curl https://api.lakefrontai.com/mandates/man_7f3a9c/budget \
  -H "Authorization: Bearer lf_your_api_key"

curl -X POST https://api.lakefrontai.com/mandates/man_7f3a9c/budget/reserve \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 4999, "scope": "payment", "currency": "USD" }'

curl -X POST https://api.lakefrontai.com/mandates/man_7f3a9c/consent \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consented_by":    "customer@example.com",
    "consent_method":  "explicit_click",
    "ip_address":      "203.0.113.42",
    "user_agent":      "Mozilla/5.0 ...",
    "terms_presented": "I authorize lakefrontai agent to charge up to $1,000 per month..."
  }'

curl https://api.lakefrontai.com/mandates/man_7f3a9c/consent \
  -H "Authorization: Bearer lf_your_api_key"

curl -X POST https://api.lakefrontai.com/mandates/man_7f3a9c/consent/revoke \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "revoked_by": "customer@example.com", "reason": "Customer request" }'

curl -X POST https://api.lakefrontai.com/disputes \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":     "ses_user_42_checkout",
    "case_reference": "CB-2026-00441",
    "reason_code":    "10.4",
    "notes":          "Customer claims they did not authorise the $49.99 charge"
  }'

curl https://api.lakefrontai.com/disputes \
  -H "Authorization: Bearer lf_your_api_key"

curl -X PATCH https://api.lakefrontai.com/disputes/dsp_7f3a9c \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "won", "notes": "Visa accepted our CE 3.0 packet" }'

curl -X POST https://api.lakefrontai.com/disputes/dsp_7f3a9c/packet \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/disputes/dsp_7f3a9c/score \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/disputes/ratio \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/fingerprints \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/fingerprints/agent_checkout_v2 \
  -H "Authorization: Bearer lf_your_api_key"

curl -X POST https://api.lakefrontai.com/fingerprints/agent_checkout_v2/reset \
  -H "Authorization: Bearer lf_your_api_key"

curl -X POST https://api.lakefrontai.com/fingerprints/backfill \
  -H "Authorization: Bearer lf_your_api_key"

curl https://api.lakefrontai.com/registry \
  -H "Authorization: Bearer lf_your_api_key"

curl -X POST https://api.lakefrontai.com/registry/reg_001/approve \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Verified with eng team — legitimate v2 deployment" }'

curl -X POST https://api.lakefrontai.com/registry/reg_001/revoke \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspected compromise — pending investigation" }'

curl -X POST https://api.lakefrontai.com/attestation/credentials \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_checkout_v2",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----",
    "allowed_image_digests": [
      "sha256:abc123def456..."
    ],
    "allowed_sbom_hashes": [
      "sha256:def456abc123..."
    ],
    "baseline_runtime": {
      "platform":     "linux",
      "arch":         "x64",
      "node_version": "v20.11.0"
    },
    "require_image_digest":  true,
    "require_sbom_hash":     false,
    "require_runtime_match": true
  }'

curl -X POST https://api.lakefrontai.com/attestation/challenge \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_checkout_v2" }'

import { createSign } from "crypto";
import { readFileSync } from "fs";

const privateKey = readFileSync("./agent_private.pem");
const message    = "lakefront-attest:agent_checkout_v2:ch_9f3a2b:a7f3e1c2d4b5...";

const sign = createSign("ed25519");
sign.update(message);
const signature = sign.sign(privateKey, "hex");

console.log(signature); // pass this to POST /attestation/verify

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives.serialization import load_pem_private_key

with open("agent_private.pem", "rb") as f:
    private_key = load_pem_private_key(f.read(), password=None)

message   = b"lakefront-attest:agent_checkout_v2:ch_9f3a2b:a7f3e1c2d4b5..."
signature = private_key.sign(message).hex()

print(signature)  # pass to POST /attestation/verify

curl -X POST https://api.lakefrontai.com/attestation/verify \
  -H "Authorization: Bearer lf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":     "agent_checkout_v2",
    "challenge_id": "ch_9f3a2b",
    "signature":    "3b6a9f...",
    "runtime": {
      "platform":     "linux",
      "arch":         "x64",
      "node_version": "v20.11.0",
      "image_digest": "sha256:abc123def456...",
      "sbom_hash":    "sha256:def456abc123..."
    }
  }'

import { createSign } from "crypto";
import { readFileSync } from "fs";
import os from "os";

const API_KEY    = process.env.LF_API_KEY;
const AGENT_ID   = "agent_checkout_v2";
const BASE_URL   = "https://api.lakefrontai.com";
const privateKey = readFileSync("./agent_private.pem");

async function attest(): Promise<string> {
  // 1. Get challenge
  const ch = await fetch(`${BASE_URL}/attestation/challenge`, {
    method:  "POST",
    headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body:    JSON.stringify({ agent_id: AGENT_ID }),
  }).then(r => r.json());

  // 2. Sign the message
  const sign = createSign("ed25519");
  sign.update(ch.message);
  const signature = sign.sign(privateKey, "hex");

  // 3. Verify and get token
  const result = await fetch(`${BASE_URL}/attestation/verify`, {
    method:  "POST",
    headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body:    JSON.stringify({
      agent_id:     AGENT_ID,
      challenge_id: ch.challenge_id,
      signature,
      runtime: {
        platform:     os.platform(),
        arch:         os.arch(),
        node_version: process.version,
        image_digest: process.env.IMAGE_DIGEST,
      },
    }),
  }).then(r => r.json());

  if (!result.verified) throw new Error(`Attestation failed: ${result.failure_reason}`);
  return result.token;
}

// 4. Use token on every event
const token = await attest();

await fetch(`${BASE_URL}/events`, {
  method:  "POST",
  headers: {
    "Authorization":        `Bearer ${API_KEY}`,
    "Content-Type":         "application/json",
    "x-attestation-token":  token,
  },
  body: JSON.stringify({ /* event payload */ }),
});

curl "https://api.lakefrontai.com/attestation/records?agent_id=agent_checkout_v2" \
  -H "Authorization: Bearer lf_your_api_key"

# In Stripe Dashboard → Developers → Webhooks → Add endpoint:
# URL: https://api.lakefrontai.com/webhooks/stripe
# Events: charge.dispute.created, charge.dispute.updated,
#          charge.refunded, payment_intent.succeeded

# Set the signing secret in your environment:
STRIPE_WEBHOOK_SECRET=whsec_your_secret

curl https://api.lakefrontai.com/compliance \
  -H "Authorization: Bearer lf_your_api_key"

curl "https://api.lakefrontai.com/timeseries?interval=day" \
  -H "Authorization: Bearer lf_your_api_key"

// Example 400 validation error
{
  "error":   "Validation failed",
  "details": [
    "event_id: Required",
    "sequence_number: Expected number, received string"
  ]
}

// Example 401
{
  "error": "Authentication required"
}

// Example 409
{
  "error": "Duplicate event_id: evt_001"
}