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

# Introduction à l'API

> Authentifiez-vous auprès de l'API REST et lancez-vous

OurAiCalling expose une API REST sous le domaine de votre plateforme. Tout ce que vous pouvez faire depuis le tableau de bord — gérer les assistants, lancer des appels, exécuter des campagnes, consulter les transcriptions — est disponible par voie programmatique.

## URL de base

```text theme={null}
https://app.famulor.io/api/v1
```

`app.famulor.io` est la plateforme hébergée. Si vous vous connectez sur un domaine locataire en marque blanche, utilisez ce domaine : l'API s'y exécute avec l'image de marque du locataire et les mêmes chemins s'appliquent.

## Authentification

Toutes les requêtes nécessitent un jeton Bearer dans l'en-tête `Authorization`. Deux types de jetons sont acceptés :

* **Clés API** (`fam_...`) — créez-les depuis **Paramètres → Clés API**. La clé complète ne s'affiche qu'une seule fois, au moment de la création ; seul un hachage est conservé ensuite. Vous pouvez éventuellement restreindre une clé à certaines portées (par exemple `assistants:read`, `calls:write`, `campaigns:write`, `dashboards:read`, `dashboards:write`, `leads:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`) et lui définir une date d'expiration. Une clé sans restriction de portée dispose d'un accès complet ; une portée `*:write` inclut automatiquement le `*:read` correspondant. Idéal pour les intégrations serveur à serveur. Les endpoints du tableau de bord acceptent aussi `calls:read/write`, si bien que les clients OAuth utilisant les quatre portées standards restent compatibles.
* **Jetons d'accès OAuth 2.0** (`fam_at_...`) — émis via le flux OAuth de la plateforme (authorization code + PKCE, enregistrement dynamique des clients). Portée limitée et durée de vie courte (1 heure, avec jetons de rafraîchissement). Idéal pour les applications tierces agissant pour le compte d'un utilisateur.

```bash theme={null}
curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"
```

<Warning>
  Traitez vos clés API comme des mots de passe. Ne les intégrez jamais dans du code côté client — pour les cas d'usage navigateur, utilisez plutôt le flux OAuth.
</Warning>

## Enveloppe de réponse

Chaque endpoint renvoie une enveloppe JSON cohérente. Les réponses réussies enveloppent la charge utile dans `data` (avec un `meta` optionnel) :

```json theme={null}
{
  "data": [ { "id": "…", "name": "Support Agent" } ],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}
```

## Ce que l'API renvoie — et ce qu'elle ne renvoie pas

L'API REST et le point de terminaison MCP renvoient la même vue délibérément sélectionnée des données de votre espace de travail : tout ce dont vous avez besoin pour développer, rien sur le fonctionnement interne de la plateforme.

Absent de toutes les réponses :

* **Identifiants d'infrastructure** — identifiants de session média, de salle, de trunk, de routage et d'opérateur de la couche téléphonie sous-jacente.
* **Chemins de stockage internes** — les enregistrements sont fournis via une URL signée à durée limitée (`GET /calls/{id}/recording`), jamais sous forme de chemin de bucket.
* **Coûts de la plateforme et détails de facturation** — coûts des fournisseurs, compteurs de tokens/caractères/secondes et suivi des débits. Votre propre consommation est exprimée dans les unités facturées : minutes et crédits (`GET /balance`, `GET /transactions`).
* **Détails internes des modèles** — quel modèle a évalué un appel ou rédigé le résumé. Le verdict, le score et le résumé sont renvoyés ; le moteur qui les produit ne l'est pas.
* **Secrets** — mots de passe, jetons et identifiants d'opérateur ne sont jamais relisibles après enregistrement ; vous obtenez au mieux un indice masqué.
* **Diagnostics d'exploitation** — les événements d'appel internes (bascules de composants, erreurs de session, écritures de consommation) sont filtrés des événements de `GET /calls/{id}`.

Tout le reste vous est ouvert : transcriptions, résumés, verdicts d'analyse, champs extraits, scores QA, contacts, campagnes, numéros et la configuration complète de l'assistant.

## Pagination

Les endpoints de liste se paginent avec les paramètres de requête `limit` et `offset` :

| Paramètre | Par défaut | Max   | Description                 |
| --------- | ---------- | ----- | --------------------------- |
| `limit`   | `50`       | `200` | Taille de page              |
| `offset`  | `0`        | —     | Nombre d'éléments à ignorer |

Le `meta.pagination.total` de la réponse indique le nombre total de résultats (indépendamment de `limit`/`offset`), ce qui vous permet de paginer jusqu'à ce que `offset + limit >= total` :

```bash theme={null}
curl "https://app.famulor.io/api/v1/calls?limit=100&offset=200" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"
```

## Erreurs

Les échecs renvoient une enveloppe d'erreur avec un `code` stable et lisible par une machine, ainsi qu'un `message` lisible par un humain :

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "\"to_number\" is required (E.164 format, e.g. +4930123456)."
  }
}
```

| Statut | Code              | Signification                                                                                        |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request` | Corps de requête ou paramètres invalides                                                             |
| `401`  | `unauthorized`    | Jeton manquant, invalide, expiré ou révoqué                                                          |
| `403`  | `forbidden`       | Portée manquante, ou fonctionnalité non incluse dans votre plan                                      |
| `404`  | `not_found`       | Ressource introuvable (ou qui ne vous appartient pas)                                                |
| `409`  | `conflict`        | La ressource est dans un état conflictuel (par exemple, arrêter une campagne qui n'est pas en cours) |
| `429`  | `rate_limited`    | Limite de débit dépassée — patientez avant de réessayer                                              |
| `500`  | `internal_error`  | Erreur serveur inattendue                                                                            |

## Limites de débit

Des limites de débit d'utilisation équitable s'appliquent par compte. Si vous les dépassez, l'API répond `429 Too Many Requests` ; patientez puis réessayez avec un backoff exponentiel. Les limites par plan seront documentées ici dès leur publication.

## MCP — utiliser l'API comme outils IA

Tout ce qui figure dans cette référence est également exposé via l'**endpoint MCP** de la plateforme (Model Context Protocol, streamable HTTP) :

```text theme={null}
https://app.famulor.io/mcp
```

Connectez Claude, ChatGPT, Cursor ou n'importe quel client MCP, et utilisez les mêmes fonctionnalités en tant qu'outils IA : mêmes services, même validation (limites de plan, catalogue de modèles, contrôles DNC) et même modèle d'autorisation (clés API ou OAuth). Nécessite la fonctionnalité de plan **Connect AI / MCP**. Guide de configuration complet : [Endpoint MCP](/api/mcp).

**Connexion rapide** — Claude et ChatGPT détectent automatiquement l'authentification (OAuth) ; les autres clients peuvent transmettre une clé API via un en-tête Bearer statique :

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http voice-ai https://app.famulor.io/mcp \
    --header "Authorization: Bearer fam_XXXXXXXXXXXX"
  ```

  ```json Cursor (~/.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "voice-ai": {
        "url": "https://app.famulor.io/mcp",
        "headers": { "Authorization": "Bearer fam_XXXXXXXXXXXX" }
      }
    }
  }
  ```

  ```json mcp-remote (OAuth) theme={null}
  {
    "mcpServers": {
      "voice-ai": {
        "command": "npx",
        "args": ["mcp-remote", "https://app.famulor.io/mcp"]
      }
    }
  }
  ```
</CodeGroup>

### Outils MCP disponibles

| Domaine                           | Outils                                                                                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assistants                        | `list_assistants`, `get_assistant`, `create_assistant`, `update_assistant`, `delete_assistant`                                                                  |
| Voix                              | `get_voices`                                                                                                                                                    |
| Appels                            | `list_calls`, `get_call`, `make_call`                                                                                                                           |
| Historique                        | `list_history`, `get_email_history_item`                                                                                                                        |
| Paramètres de l'espace de travail | `list_email_senders`, `get_custom_domain`, `add_custom_domain`, `verify_custom_domain`, `remove_custom_domain`, `get_memory_settings`, `update_memory_settings` |
| Campagnes                         | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign`, `start_campaign`, `stop_campaign`                                    |
| Leads                             | `list_leads`, `add_lead`, `add_leads`, `delete_lead`                                                                                                            |
| Numéros de téléphone              | `list_phone_numbers`, `search_phone_numbers`, `buy_phone_number`, `release_phone_number`, `assign_phone_number`                                                 |
| Trunks SIP                        | `list_sip_trunks`, `get_sip_trunk`, `create_sip_trunk`, `delete_sip_trunk`                                                                                      |
| Bases de connaissances            | `list_knowledge_bases`, `get_knowledge_base`, `create_knowledge_base`, `delete_knowledge_base`, `add_document`                                                  |
| Compte et facturation             | `get_balance`, `get_me`, `get_usage_summary`                                                                                                                    |