Quickstart — Aeliam Public API¶

Audience: developers integrating Aeliam into a CRM, an automation tool (n8n / Zapier), or a script.

All examples target DEV (https://dev.aeliam.ai). For production, only the host changes (app.aeliam.ai) — see Environments.

Base URL:  https://dev.aeliam.ai/api/v1/public
Auth:      X-API-Key: aelm_dev_<random>     (or Authorization: Bearer aelm_dev_<random>)

0. Get a key¶

Console → https://dev.aeliam.ai → API keys (/cabinet/api-keys) → New key → pick the environment and scopes → copy it once (aelm_dev_…, never shown again). See Démarrage (FR) for the walkthrough.

1. curl¶

Check authentication¶

curl -H "X-API-Key: aelm_dev_xxxxxxxx" \
     https://dev.aeliam.ai/api/v1/public/me

List opportunities (paginated)¶

curl -H "X-API-Key: aelm_dev_xxxxxxxx" \
     "https://dev.aeliam.ai/api/v1/public/opportunities?limit=10"

# Next page — the cursor is HMAC-signed, never forge it
curl -H "X-API-Key: aelm_dev_xxxxxxxx" \
     "https://dev.aeliam.ai/api/v1/public/opportunities?limit=10&cursor=<next_cursor>"

Download a quote PDF¶

# Returns 302 → time-limited signed URL (Supabase Storage, ~5 min TTL)
curl -L -H "X-API-Key: aelm_dev_xxxxxxxx" \
     https://dev.aeliam.ai/api/v1/public/devis/<devis_id>/pdf \
     -o devis.pdf

2. Python¶

pip install httpx

import httpx

class AeliamClient:
    def __init__(self, api_key: str, base_url: str = "https://dev.aeliam.ai"):
        self.client = httpx.Client(
            base_url=f"{base_url}/api/v1/public",
            headers={"X-API-Key": api_key},
            timeout=30.0,
        )

    def me(self):
        r = self.client.get("/me")
        r.raise_for_status()
        return r.json()

    def list_opportunities(self, *, limit=50, cursor=None, stage=None):
        params = {"limit": limit}
        if cursor:
            params["cursor"] = cursor
        if stage:
            params["stage"] = stage
        r = self.client.get("/opportunities", params=params)
        r.raise_for_status()
        return r.json()

    def iter_opportunities(self, **filters):
        cursor = None
        while True:
            page = self.list_opportunities(cursor=cursor, **filters)
            yield from page["data"]
            if not page["has_more"]:
                return
            cursor = page["next_cursor"]

client = AeliamClient(api_key="aelm_dev_xxxxxxxx")
print(client.me())
for opp in client.iter_opportunities(stage="nouveau"):
    print(opp["id"], opp["name"], opp["amount"])

3. JavaScript / Node¶

class AeliamClient {
  constructor(apiKey, baseUrl = 'https://dev.aeliam.ai') {
    this.apiKey = apiKey;
    this.base = `${baseUrl}/api/v1/public`;
  }

  async _fetch(path, init = {}) {
    const res = await fetch(`${this.base}${path}`, {
      ...init,
      headers: { 'X-API-Key': this.apiKey, ...(init.headers || {}) },
    });
    if (!res.ok) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`${res.status} ${body?.error || res.statusText}`);
    }
    return res.json();
  }

  me() { return this._fetch('/me'); }

  async *iterOpportunities({ stage, createdAfter } = {}) {
    let cursor = null;
    do {
      const params = new URLSearchParams({ limit: '50' });
      if (stage) params.set('stage', stage);
      if (createdAfter) params.set('created_after', createdAfter);
      if (cursor) params.set('cursor', cursor);
      const page = await this._fetch(`/opportunities?${params}`);
      for (const opp of page.data) yield opp;
      cursor = page.has_more ? page.next_cursor : null;
    } while (cursor);
  }
}

const aeliam = new AeliamClient(process.env.AELIAM_API_KEY);
console.log(await aeliam.me());

4. n8n¶

A simple recurring pull → push pattern:

[Cron 5 min] → [HTTP GET /opportunities?created_after={{ $now.minus(5, 'minutes') }}]
            → [Filter / dedupe] → [Create row in HubSpot / Notion / Sheet]

HTTP Request node: method GET, URL https://dev.aeliam.ai/api/v1/public/opportunities, header X-API-Key: aelm_dev_xxxxxxxx (Auth = None, the header does the work).
For writes (create lead, enqueue tarification), POST with an Idempotency-Key header — see Idempotency & quotas.

The flagship flow: automated tarification¶

Get a real insurer quote end-to-end from your integration:

KEY="aelm_dev_xxxxxxxx"
BASE="https://dev.aeliam.ai/api/v1/public"

# 1. Required fields for the product/insurer
curl -H "X-API-Key: $KEY" "$BASE/produits-disponibles/mrp/schema?compagnie=axa"

# 2. Validate the whole pipeline first — no cost, no job created
curl -X POST "$BASE/automation/tarifications" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"compagnie":"axa","produit":"mrp","dry_run":true,
       "dicData":{"raison_sociale":"Acme","siret":"00000000000000"}}'

# 3. Trigger the real tarification (RPA robot on the insurer portal)
curl -X POST "$BASE/automation/tarifications" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"compagnie":"axa","produit":"mrp",
       "dicData":{"raison_sociale":"Acme","siret":"00000000000000", "...": "..."}}'
# → { "job_id": "...", "status": "pending", "poll_url": "/api/v1/public/automation/jobs/..." }

# 4. Poll until terminal (completed / failed)
curl -H "X-API-Key: $KEY" "$BASE/automation/jobs/<job_id>"
# → result: { "tarif_eur": 376.65, "suspens": "0000022...", "pdf_url": "/api/v1/public/devis/<id>/pdf" }

# 5. Fetch the PDF (302 → signed URL)
curl -L -H "X-API-Key: $KEY" "$BASE/devis/<devis_id>/pdf" -o devis.pdf

A tarification takes ~60–180 s. Mind the quotas and anti-replay rules and prefer dry_run while developing.

Security checklist¶

❌ Never commit a key to git → use .env / a secrets manager.
❌ Never expose a key in browser-side JavaScript → proxy through your backend.
✅ Restrict allowed IPs (optional ip_allowlist at key creation).
✅ Set an expiration for CI/CD keys (rotation).
✅ Revoke any suspected-compromised key immediately from the console.

Support¶

Live API reference (OpenAPI / Scalar): API Reference
Questions: api@aeliam.ai · Security: security@aeliam.ai