> ## 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.

# Generate Intent

> Creates a zero-knowledge intent signature for a user session

## Overview

Generates a User Intent Signature (UIS) — a SHA-256 hash that represents what a user intends to do, without including any PII.

Call this **before** sending a user's request to your AI service. Attach the returned `intent_hash` to the AI request via the `X-Intent-Hash` header.

***

## Request

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

<ParamField body="user_token" type="string" required>
  The user's JWT from your authentication system. Used to fetch semantic context from AetherDB. The token itself is never stored by Citadel.
</ParamField>

<ParamField body="ttl" type="integer" default="3600">
  Time-to-live in seconds for this intent signature. After expiry, verify will return `ExpiredIntent`. Default: 3600 (1 hour). Max recommended: 86400 (24h).
</ParamField>

***

## Response

<ResponseField name="intent_hash" type="string">
  The zero-knowledge intent signature. Format: `sha256:<64 hex chars>`. Attach this to your AI request as `X-Intent-Hash`.
</ResponseField>

<ResponseField name="intent_class" type="string">
  Semantic classification of user intent. One of: `commerce`, `infrastructure`, `wellness`, `finance`, `education`, `social`, `other`.
</ResponseField>

<ResponseField name="expires_at" type="integer">
  Unix timestamp when this intent expires. After this time, verification will fail with `ExpiredIntent`.
</ResponseField>

***

## Example

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

**200 Response:**

```json theme={null}
{
  "intent_hash": "sha256:a3f8c2d1e5b9047263a1c4d7e8f2b3a9c6d5e4f1a2b3c4d5e6f7a8b9c0d1e2f3",
  "intent_class": "commerce",
  "expires_at": 1718003600
}
```

***

## Error Responses

| Status | Error                               | Meaning                                 |
| ------ | ----------------------------------- | --------------------------------------- |
| `400`  | `token too short`                   | `user_token` is less than 10 characters |
| `400`  | `token contains invalid characters` | Non-alphanumeric/JWT chars in token     |
| `401`  | `invalid or missing X-Citadel-Key`  | Bad or missing API key                  |
| `502`  | `AetherDB request failed`           | Could not fetch semantic context        |

***

## Notes

* The `user_token` is sent to AetherDB (within your infrastructure) to extract semantic tags. It is **never stored** by Citadel.
* Each call generates a **new, unique** intent hash — even for the same user.
* Intent hashes are **single-use** — do not reuse them across different AI requests.