Quickstart

Step 1 — Get an API Key

Choose a plan

Visit our pricing page and select a plan. Payment takes under 60 seconds.

Check your email

After payment, you’ll receive an email from keys@aethercitadel.cloud with your API key:

ack_live_a1b2c3d4e5f6...

Keep it secret

This key controls your allocation. Don’t commit it to git or expose it in client-side code. Store it as an environment variable.

Step 2 — Generate an Intent

Before your app serves AI output to a user, generate an intent signature:

curl -X POST https://api.aethercitadel.cloud/v1/intent/generate \
  -H "X-Citadel-Key: ack_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_token": "eyJhbGciOiJIUzI1NiJ9...",
    "ttl": 3600
  }'

const response = await fetch('https://api.aethercitadel.cloud/v1/intent/generate', {
  method: 'POST',
  headers: {
    'X-Citadel-Key': process.env.CITADEL_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_token: userJwt,
    ttl: 3600,
  }),
});

const { intent_hash, intent_class, expires_at } = await response.json();

import httpx

resp = httpx.post(
    "https://api.aethercitadel.cloud/v1/intent/generate",
    headers={"X-Citadel-Key": CITADEL_API_KEY},
    json={"user_token": user_jwt, "ttl": 3600},
)
data = resp.json()
intent_hash = data["intent_hash"]

Response:

{
  "intent_hash": "sha256:a1b2c3d4e5f6...",
  "intent_class": "commerce",
  "expires_at": 1718000000
}

Store the intent_hash — you’ll need it in step 3.

Step 3 — Call Your AI

Pass the intent_hash to your AI service using the X-Intent-Hash header:

const aiResponse = await fetch('https://your-ai-service.com/api/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${userToken}`,
    'X-Intent-Hash': intentHash,   // ← attach the hash
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ prompt: userInput }),
});

Step 4 — Verify the Response

After the AI responds, verify it hasn’t been tampered with:

curl -X POST https://api.aethercitadel.cloud/v1/intent/verify \
  -H "X-Citadel-Key: ack_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_intent_hash": "sha256:a1b2c3d4...",
    "response": {
      "match_id": "resp_xyz",
      "payload": { "text": "AI output here..." },
      "timestamp": 1718000100,
      "signature": "hmac_sig..."
    }
  }'

const verify = await fetch('https://api.aethercitadel.cloud/v1/intent/verify', {
  method: 'POST',
  headers: {
    'X-Citadel-Key': process.env.CITADEL_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    original_intent_hash: intentHash,
    response: aiScaleResponse,
  }),
});

const { cleared, reason } = await verify.json();

if (!cleared) {
  console.error('Blocked by Bharat-Shield:', reason);
}

Response:

{
  "cleared": true,
  "reason": null,
  "payload": { "text": "AI output here..." }
}

Check Your Usage

At any time, check your usage against your plan limit:

curl https://api.aethercitadel.cloud/v1/tenant/usage \
  -H "X-Citadel-Key: ack_live_YOUR_KEY"

{
  "email": "you@company.com",
  "plan": "Citadel Starter",
  "usage_count": 1234,
  "rate_limit": 50000,
  "remaining": 48766
}

Next Steps

Authentication

How API keys work and how to rotate them

Zero-Knowledge

How we protect user privacy

Bharat-Shield

What threats we block automatically

Full API Reference

All endpoints, parameters and response shapes

Getting Started

Core Concepts

Changelog

Step 1 — Get an API Key

Step 2 — Generate an Intent

Step 3 — Call Your AI

Step 4 — Verify the Response

Check Your Usage

Next Steps

Authentication

Zero-Knowledge

Bharat-Shield

Full API Reference

​Step 1 — Get an API Key

​Step 2 — Generate an Intent

​Step 3 — Call Your AI

​Step 4 — Verify the Response

​Check Your Usage

​Next Steps

Authentication

Zero-Knowledge

Bharat-Shield

Full API Reference

Step 1 — Get an API Key

Step 2 — Generate an Intent

Step 3 — Call Your AI

Step 4 — Verify the Response

Check Your Usage

Next Steps