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

# POST /api/agent

> Send a message to the AI wealth intelligence agent

# Agent

Send a conversation to the iNwealth AI agent and receive a streaming response.

## Request

<ParamField body="messages" type="object[]" required>
  Conversation history.

  <Expandable title="Message object">
    <ParamField body="role" type="string" required>
      `"user"` for the end-user's message, `"assistant"` for previous AI responses. First message is always `"user"`. Include previous turns to maintain conversation context.
    </ParamField>

    <ParamField body="content" type="string" required>
      Message text
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="session_id" type="string" required>
  Unique session identifier (client-side). Reuse the same ID for a conversation to benefit from Anthropic's prompt caching.
</ParamField>

<ParamField body="residence" type="string" default="fr">
  Country code for the end-user's tax residence. The agent adapts its answers to local legislation.

  Supported: `fr`, `ch`, `it`, `be`, `lu`, `de`, `es`, `pt`, `gb`, `mc`, `gr`, `ad`, `nl`, `us`, `mu`, `ma`, `intl`
</ParamField>

<ParamField body="language" type="string" default="fr">
  Response language. Supported: `fr`, `en`, `de`, `es`, `it`, `pt`
</ParamField>

<ParamField body="extended_thinking" type="boolean" default={false}>
  Enable Claude's native extended thinking mode. The agent reasons explicitly before answering — recommended for complex or cross-border questions.
</ParamField>

<ParamField body="effort" type="string">
  Analysis depth. Controls how deeply the agent analyzes the question.

  Values: `low`, `medium`, `high`, `max`, or `null` (auto — the agent decides based on complexity).
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://api.inwealth.fr/api/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d '{
    "messages": [
      {"role": "user", "content": "Compare taxation of stock options in France vs Switzerland"}
    ],
    "session_id": "session-001",
    "residence": "fr",
    "language": "en",
    "extended_thinking": true,
    "effort": "high"
  }'
```

## Response

The response is a **streaming SSE** (`text/event-stream`) with five event types:

| Event           | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `delta`         | Text fragment (content or thinking) — append to your display      |
| `metadata`      | Metadata about the response (sources, markers)                    |
| `done`          | End of stream with final message                                  |
| `error`         | Error during streaming (rate limit, internal error)               |
| `clarification` | Clarifying questions before answering — collect user input (V170) |

```
event: delta
data: {"type": "delta", "delta": {"content": "Stock options are taxed differently "}}

event: delta
data: {"type": "delta", "delta": {"content": "in France and Switzerland..."}}

event: metadata
data: {"type": "metadata", "data": {"markers": [...]}}

event: done
data: {"type": "done", "final_message": {"role": "assistant", "content": "..."}}
```

When `extended_thinking` is enabled, delta events can also contain thinking data:

```
event: delta
data: {"type": "delta", "delta": {"thinking": "Analyzing cross-border implications...", "phase": "RECHERCHE", "step": "Exit tax treaty provisions"}}
```

## Error responses

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `200`  | OK — SSE stream                            |
| `401`  | Invalid or revoked API key                 |
| `400`  | Invalid parameters (e.g. bad effort value) |
| `422`  | Missing required fields                    |
| `429`  | Daily token quota exceeded                 |