# API Documentation

## Auto-Provisioned Trial Keys

Mnexium automatically provisions trial API keys for anonymous users. When you make a request without an `x-mnexium-key` header, we create a trial key based on your device fingerprint (IP + User-Agent).

How it works

- First request without a key → new trial key created
- Same device, no key → same trial key reused (no key returned)
- Different device → different trial key
- Trial keys have no expiry — they work until claimed or revoked

## Response with Provisioned Key

When a new trial key is provisioned, it's returned in both the response headers and body:

```javascript
// Response Headers
X-Mnx-Key-Provisioned: mnx_trial.abc123...
X-Mnx-Claim-Url: https://mnexium.com/claim

// Response Body
{
  "choices": [...],
  "mnx": {
    "chat_id": "...",
    "subject_id": "...",
    "provisioned_key": "mnx_trial.abc123...",
    "claim_url": "https://mnexium.com/claim"
  }
}
```

**Important:** save your key

The full trial key is only returned **once** when first provisioned. Save it immediately — subsequent requests from the same device won't return the key again.

## Key Recovery with regenerate_key

If a trial key is unavailable, use `regenerate_key: true` to issue a replacement key. The previous key is revoked while project data is preserved.

```javascript
const response = await fetch("https://mnexium.com/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-openai-key": "sk-..."
    // No x-mnexium-key
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Remember that I prefer dark mode" }],
    mnx: {
      regenerate_key: true  // Forces new key
    }
  })
});

// Response includes new key in headers + body
```

## Claiming Your Trial Key

Convert your trial key to a full account to access the dashboard, create more keys, and manage your data.

1. Go to [mnexium.com/claim](/content/claim/index.html)
2. Paste your trial key (e.g., `mnx_trial.abc123...`)
3. Sign in or create an account
4. Click "Claim This Key" — your key and project are now linked to your account

**✓ Data preserved**

All memories, chats, and profiles created during your trial are transferred to your account.

## Trial Key Limits

Trial keys have the same usage limits as regular keys. Usage is tracked per fingerprint.

| Feature          | Limit                         |
|------------------|-------------------------------|
| API calls        | Up to 10,000 per month        |
| Memory actions   | Up to 1,000 per month         |
| Expiry           | none                          |
| Scopes           | full                          |