> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aethercitadel.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Response

> Verifies an AI response against its original intent signature via Bharat-Shield

## Overview

Passes an AI response through Bharat-Shield for verification. Confirms that the response legitimately corresponds to the original intent, and hasn't been tampered with, replayed, or generated outside the expected context.

Call this **after** your AI service responds, **before** serving the output to the user.

***

## Request

<ParamField header="X-Citadel-Key" type="string" required>
  Your Aether Citadel API key (`ack_live_...`)
</ParamField>

<ParamField body="original_intent_hash" type="string" required>
  The `intent_hash` returned by `/v1/intent/generate`. Must be in the format `sha256:<64 hex chars>`.
</ParamField>

<ParamField body="response" type="object" required>
  The `ScaleResponse` object from your AI service.

  <Expandable title="ScaleResponse fields">
    <ParamField body="match_id" type="string" required>
      Unique ID for this response, generated by your AI service.
    </ParamField>

    <ParamField body="payload" type="object" required>
      The AI output payload — any JSON object.
    </ParamField>

    <ParamField body="timestamp" type="integer" required>
      Unix timestamp when the AI generated this response.
    </ParamField>

    <ParamField body="signature" type="string" required>
      HMAC-SHA256 signature of the payload, generated by AetherScale/your AI service.
    </ParamField>
  </Expandable>
</ParamField>

***

## Response

<ResponseField name="cleared" type="boolean">
  `true` if Bharat-Shield approved the response. `false` if blocked.
</ResponseField>

<ResponseField name="reason" type="string | null">
  If `cleared` is `false`, the block reason. See [block reasons](/guides/bharat-shield#block-reasons).
</ResponseField>

<ResponseField name="payload" type="object | null">
  The verified AI payload. Only present when `cleared` is `true`. Serve this to the user.
</ResponseField>

***

## Example

<CodeGroup>
  ```bash cURL theme={null}
  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:a3f8c2d1...",
      "response": {
        "match_id": "resp_abc123",
        "payload": { "text": "Here is your answer..." },
        "timestamp": 1718001000,
        "signature": "3a4b5c6d..."
      }
    }'
  ```

  ```typescript Node.js theme={null}
  const res = 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: scaleResponse,
    }),
  });

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

  if (!cleared) {
    // Block the response — do not show to user
    logger.warn('Citadel blocked AI response:', reason);
    return res.status(403).json({ error: 'AI response blocked' });
  }

  // Safe to serve
  return res.json(payload);
  ```
</CodeGroup>

**Cleared response:**

```json theme={null}
{
  "cleared": true,
  "reason": null,
  "payload": { "text": "Here is your answer..." }
}
```

**Blocked response:**

```json theme={null}
{
  "cleared": false,
  "reason": "ExpiredIntent",
  "payload": null
}
```

***

## Error Responses

| Status | Error                                   | Meaning                  |
| ------ | --------------------------------------- | ------------------------ |
| `400`  | `intent hash must start with 'sha256:'` | Invalid hash format      |
| `400`  | `intent hash has invalid length`        | Hash is not 64 hex chars |
| `401`  | `invalid or missing X-Citadel-Key`      | Bad or missing API key   |