Référence API

API Utilisation

Lisez votre utilisation par programme et configurez des alertes webhook quand l'utilisation dépasse un seuil.Lectures. Portée usage:read ; couvre GET /usage, /usage/summary, /usage/daily, /usage/monthly.Gestion des déclencheurs. Portée usage:write ; créez, mettez à jour, faites tourner le secret webhook.Fraîcheur des données. Les lignes d'utilisation sont validées en quelques secondes après la fin de la requête ; les agrégats reflètent généralement l'activité en moins d'une minute.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 10
Portées: usage:readusage:write

GET/usage

Totaux à vie pour chaque ressource facturée, plus un nombre de requêtes par bucket.

Obtenir le résumé d'utilisation

Totaux à vie pour chaque ressource facturée sur ce compte. Retourne les nombres de requêtes, les totaux de tokens, les secondes audio, et une décomposition par type de ressource.total_request_duration_ms s'applique uniquement aux ressources synchrones (agent_chat, tts, transcription) ; les appels vocaux apparaissent sous total_voice_seconds (temps actif de l'agent, capturé en fin d'appel). Nécessite la portée usage:read.

Chemin & Requête

api_key_idstring (uuid)optionnel
Limite les chiffres à l'utilisation enregistrée pour cette seule clé API. Toujours limité à votre espace de travail : l'identifiant d'une clé appartenant à un autre tenant, ou inexistant, renvoie des zéros plutôt qu'une erreur.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY avec une clé ayant la portée usage:read.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une nouvelle clé avec usage:read.

Requête

json

curl -X GET https://api.aethexai.com/api/v1/usage \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "total_api_requests": 4280,
  "total_request_duration_ms": 259200000,
  "total_voice_seconds": 18420.5,
  "total_prompt_tokens": 412000,
  "total_completion_tokens": 198000,
  "total_tokens": 610000,
  "total_audio_seconds": 21340.0,
  "total_input_characters": 845000,
  "by_resource_type": {
    "voice_call": {
      "count": 1250,
      "prompt_tokens": 312000,
      "completion_tokens": 148000,
      "total_tokens": 460000,
      "audio_seconds": 18420.5,
      "input_characters": 0
    },
    "transcription": {
      "count": 980,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 50000,
      "audio_seconds": 2919.5,
      "input_characters": 0
    },
    "tts": {
      "count": 1200,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 100000,
      "audio_seconds": 0.0,
      "input_characters": 845000
    },
    "agent": {
      "count": 420,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "audio_seconds": 0.0,
      "input_characters": 0
    }
  }
}

GET/usage/summary

Identique à `GET /usage` ; conservé comme alias pratique.

Obtenir le résumé d'utilisation (alias)

Alias pour GET /usage retournant le même payload. Nécessite la portée usage:read.

Chemin & Requête

api_key_idstring (uuid)optionnel
Limite les chiffres à l'utilisation enregistrée pour cette seule clé API. Toujours limité à votre espace de travail : l'identifiant d'une clé appartenant à un autre tenant, ou inexistant, renvoie des zéros plutôt qu'une erreur.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une clé avec usage:read.

Requête

json

curl -X GET https://api.aethexai.com/api/v1/usage/summary \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "total_api_requests": 4280,
  "total_request_duration_ms": 259200000,
  "total_voice_seconds": 18420.5,
  "total_prompt_tokens": 412000,
  "total_completion_tokens": 198000,
  "total_tokens": 610000,
  "total_audio_seconds": 21340.0,
  "total_input_characters": 845000,
  "by_resource_type": {
    "voice_call": {
      "count": 1250,
      "prompt_tokens": 312000,
      "completion_tokens": 148000,
      "total_tokens": 460000,
      "audio_seconds": 18420.5,
      "input_characters": 0
    },
    "transcription": {
      "count": 980,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 50000,
      "audio_seconds": 2919.5,
      "input_characters": 0
    },
    "tts": {
      "count": 1200,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 100000,
      "audio_seconds": 0.0,
      "input_characters": 845000
    }
  }
}

GET/usage/daily

Agrégat journalier sur une fenêtre glissante, par défaut les 30 derniers jours.

Obtenir l'utilisation quotidienne

Agrégat journalier sur une fenêtre glissante en jours calendaires UTC. Retourne exactement days entrées — une par jour, la plus récente en premier — avec les jours sans activité remplis de zéros, afin que la réponse soit prête pour un graphique sans gestion des trous côté client. Chaque entrée a la date, le nombre de requêtes, les tokens prompt / completion / total, la durée de requête (ressources HTTP uniquement), voice_seconds (temps actif de l'agent, capturé en fin d'appel), audio_seconds, et les caractères d'entrée. Nécessite la portée usage:read.

Chemin & Requête

daysintegeroptionnel
Longueur de la fenêtre glissante en jours calendaires. Par défaut 30. Doit être compris entre 1 et 365 inclus ; les valeurs hors de cette plage retournent 422.
api_key_idstring (uuid)optionnel
Limite les chiffres à l'utilisation enregistrée pour cette seule clé API. Toujours limité à votre espace de travail : l'identifiant d'une clé appartenant à un autre tenant, ou inexistant, renvoie des zéros plutôt qu'une erreur.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une clé avec usage:read.

422Entité non traitable

days est hors de la plage 1..365.

Passez un entier entre 1 et 365 inclus.

Requête

json

curl -X GET 'https://api.aethexai.com/api/v1/usage/daily?days=30' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

[
  {
    "date": "2025-01-15",
    "count": 142,
    "prompt_tokens": 12300,
    "completion_tokens": 5400,
    "total_tokens": 17700,
    "request_duration_ms": 184000,
    "voice_seconds": 612.4,
    "audio_seconds": 698.2,
    "input_characters": 28400
  }
]

GET/usage/monthly

Agrégat mensuel ; chaque bucket est ancré au premier du mois en UTC.

Obtenir l'utilisation mensuelle

Agrégat mensuel, chaque bucket ancré au premier du mois en UTC. Mêmes champs que GET /usage/daily agrégés en buckets mensuels, sur toute la période de rétention du compte.

Chemin & Requête

api_key_idstring (uuid)optionnel
Limite les chiffres à l'utilisation enregistrée pour cette seule clé API. Toujours limité à votre espace de travail : l'identifiant d'une clé appartenant à un autre tenant, ou inexistant, renvoie des zéros plutôt qu'une erreur.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une clé avec usage:read.

Requête

json

curl -X GET https://api.aethexai.com/api/v1/usage/monthly \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

[
  {
    "month": "2025-01-01 00:00:00+00:00",
    "count": 4280,
    "prompt_tokens": 412000,
    "completion_tokens": 198000,
    "total_tokens": 610000,
    "request_duration_ms": 5184000,
    "voice_seconds": 18420.5,
    "audio_seconds": 21340.0,
    "input_characters": 845000
  }
]

POST/usage/triggers

Enregistrer un webhook à déclencher quand l'utilisation dépasse un seuil pour la période.

Créer un déclencheur d'utilisation

Enregistre un webhook qui se déclenche une fois par période quand l'utilisation dépasse un seuil. Le déclencheur se recharge à la limite de période suivante.Prérequis. Faites tourner un secret webhook via POST /usage/webhook-secret/rotate avant de créer votre premier déclencheur.Nécessite la portée usage:write.

Corps de la requête

resource_typestringrequis
Compartiment à surveiller. L'un de voice_call, transcription, tts, agent_chat, all. all correspond à tous les types de ressources dans le threshold_type sélectionné.
threshold_valuenumber (decimal)requis
Valeur de seuil. Doit être > 0, max 38 chiffres / 6 décimales.
threshold_typestringoptionnel
Comment threshold_value est interprété. L'un de count (par défaut) ou credits_used.
periodstringoptionnel
Fenêtre glissante. L'un de monthly (par défaut) ou daily.
event_callback_urlstringrequis
URL HTTPS qui reçoit le POST signé quand le seuil se déclenche. Doit résoudre vers une IP publique.

Erreurs

400Pas de secret webhook

Votre compte n'a pas de webhook_secret configuré, donc le déclencheur ne peut pas signer les callbacks.

Appelez d'abord POST /usage/webhook-secret/rotate pour en générer un, puis réessayez.

422Format d'URL de callback invalide

event_callback_url a échoué à la validation du schéma : l'URL ne commence pas par https:// ou contient des espaces. Retourné avec code: "validation_error" et le champ en cause dans le tableau detail.

Utilisez une URL HTTPS valide sans espaces.

400URL de callback bloquée

event_callback_url a été rejetée à l'étape de politique d'URL. Causes courantes : le nom d'hôte résolu vers une IP privée, de loopback ou de métadonnées cloud ; l'URL contenait des identifiants (user:pass@host) ou un fragment (#...) ; le port n'était pas 443. Retourné avec code: "bad_request".

Utilisez une URL HTTPS résolvable publiquement sur votre propre domaine.

503Validation d'URL temporairement indisponible

La résolution DNS a échoué lors de la validation de event_callback_url. Deux causes distinctes partagent ce statut : le résolveur est temporairement indisponible (transitoire — réessai sûr) OU le nom d'hôte ne peut pas être résolu (faute de frappe / DNS non configuré — les réessais échoueront aussi). Retourné avec code: "service_unavailable".

Vérifiez que le nom d'hôte résout publiquement (par ex. dig +short your-host.example.com) ; les noms d'hôte invalides ou mal orthographiés apparaissent aussi ici. Si le nom d'hôte est valide, réessayez avec un backoff exponentiel — des échecs persistants avec un nom d'hôte vérifié indiquent une panne du résolveur ; contactez le support avec le request_id.

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:write.

Émettez une clé avec usage:write.

409Plafond de déclencheurs atteint

Vous êtes déjà au maximum de déclencheurs actifs pour le compte.

Définissez is_active: false sur un déclencheur inutilisé pour libérer un slot avant d'en créer un nouveau.

422Champ invalide

resource_type, threshold_type, ou period n'est pas dans l'ensemble autorisé, ou threshold_value est hors limites.

Utilisez l'une des valeurs documentées ci-dessus.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/usage/triggers \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "voice_call",
    "threshold_value": 1000,
    "threshold_type": "count",
    "period": "monthly",
    "event_callback_url": "https://hooks.your-domain.example/aethex/usage"
  }'

201 Réponse

json

{
  "id": "trigger-uuid",
  "resource_type": "voice_call",
  "threshold_value": "1000.000000",
  "threshold_type": "count",
  "period": "monthly",
  "event_callback_url": "https://hooks.your-domain.example/aethex/usage",
  "is_active": true,
  "created_at": "2025-01-20T12:00:00Z",
  "last_fired_at": null
}

GET/usage/triggers

Retourner tous les déclencheurs d'utilisation configurés pour le compte, actifs ou non.

Lister les déclencheurs d'utilisation

Retourne tous les déclencheurs d'alerte d'utilisation configurés pour le compte appelant, y compris les désactivés. Nécessite la portée usage:read.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une clé avec usage:read.

Requête

json

curl -X GET https://api.aethexai.com/api/v1/usage/triggers \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

[
  {
    "id": "trigger-uuid",
    "resource_type": "voice_call",
    "threshold_value": "1000.000000",
    "threshold_type": "count",
    "period": "monthly",
    "event_callback_url": "https://hooks.your-domain.example/aethex/usage",
    "is_active": true,
    "created_at": "2025-01-20T12:00:00Z",
    "last_fired_at": "2025-01-22T03:14:00Z"
  }
]

PATCH/usage/triggers/:trigger_id

Ajuster `is_active` / `threshold_value` / `event_callback_url` ; la forme du déclencheur est immuable.

Mettre à jour un déclencheur d'utilisation

Mise à jour partielle d'un déclencheur. Seuls is_active, threshold_value, et event_callback_url sont modifiables. resource_type, threshold_type, et period sont immuables ; créez un nouveau déclencheur si vous avez besoin d'une forme différente. Nécessite la portée usage:write.

Chemin & Requête

trigger_idstringrequis
UUID du déclencheur

Corps de la requête

is_activebooleanoptionnel
Désactivation douce sans supprimer l'historique. La réactivation revérifie le plafond des déclencheurs actifs.
threshold_valuenumber (decimal)optionnel
Décimal, > 0, max 38 chiffres / 6 décimales.
event_callback_urlstringoptionnel
URL HTTPS ; remplace l'URL actuelle de manière atomique.

Erreurs

422Format d'URL de callback invalide

Utilisez une URL HTTPS valide sans espaces.

400URL de callback bloquée

Utilisez une URL HTTPS résolvable publiquement sur votre propre domaine.

503Validation d'URL temporairement indisponible

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:write.

Émettez une clé avec usage:write.

404Déclencheur introuvable

Le déclencheur n'existe pas ou n'appartient pas au compte appelant.

Vérifiez l'ID du déclencheur via GET /usage/triggers.

409Plafond de déclencheurs actifs atteint

La réactivation vous ferait dépasser le plafond des déclencheurs actifs.

Désactivez un autre déclencheur avant de réactiver celui-ci.

422Champ invalide

threshold_value est hors limites.

Envoyez une valeur dans les limites documentées.

Requête

json

curl -X PATCH https://api.aethexai.com/api/v1/usage/triggers/trigger-uuid \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Réponse 200

json

{
  "id": "trigger-uuid",
  "resource_type": "voice_call",
  "threshold_value": "1000.000000",
  "threshold_type": "count",
  "period": "monthly",
  "event_callback_url": "https://hooks.your-domain.example/aethex/usage",
  "is_active": false,
  "created_at": "2025-01-20T12:00:00Z",
  "last_fired_at": "2025-01-22T03:14:00Z"
}

POST/usage/webhook-secret/rotate

Générer un nouveau secret HMAC-SHA256 à l'échelle du compte utilisé pour signer chaque webhook de déclencheur.

Faire tourner le secret webhook d'utilisation

Génère (ou remplace) le secret de signature webhook au niveau du compte. La valeur en clair est retournée une seule fois dans cette réponse ; stockez-la avant la fin de la requête. Nous ne l'exposons plus jamais. La valeur retournée est une chaîne hexadécimale minuscule de 64 caractères prête pour l'utilisation dans un vérificateur HMAC-SHA256.Format de signature. Chaque callback de déclencheur envoie un en-tête X-Aethex-Signature au format t=<unix_timestamp>,v1=<hex_hmac> et un en-tête X-Aethex-Event: usage.threshold.crossed. Pour vérifier : HMAC-SHA256 sur la chaîne "<t>.<raw_body>" avec votre secret et comparez à v1 en temps constant. Rejetez les callbacks dont t s'écarte de plus de 5 minutes de votre horloge pour atténuer les attaques par rejeu.Impact de la rotation. Prend effet immédiatement ; les callbacks en transit signés avec l'ancien secret échoueront à la vérification. Effectuez la rotation pendant les fenêtres à faible trafic et utilisez POST /usage/triggers/{id}/firings/{firing_id}/redeliver pour rejouer les callbacks ayant échoué pendant la transition.Nécessite la portée usage:write.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:write.

Émettez une clé avec usage:write.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/usage/webhook-secret/rotate \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "webhook_secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

GET/usage/triggers/:trigger_id/firings

Journal d'audit des dépassements de seuil pour un déclencheur, du plus récent au plus ancien.

Lister les déclenchements

Journal d'audit des dépassements de seuil pour ce déclencheur, du plus récent au plus ancien.Une ligne par dépassement, pas par tentative de livraison. Quand vous relancez un déclenchement, attempt_count s'incrémente ; aucune nouvelle ligne n'est insérée.delivery_status est delivered (2xx final), failed (tous les réessais épuisés), ou pending (en transit).Nécessite la portée usage:read.

Chemin & Requête

trigger_idstringrequis
UUID du déclencheur
limitintegeroptionnel
Nombre max de lignes à retourner. Limité à 1..200 ; par défaut 50.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:read.

Émettez une clé avec usage:read.

404Déclencheur introuvable

Le déclencheur n'existe pas ou n'appartient pas au compte appelant.

Vérifiez l'ID du déclencheur via GET /usage/triggers.

Requête

json

curl -X GET 'https://api.aethexai.com/api/v1/usage/triggers/trigger-uuid/firings?limit=50' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

[
  {
    "id": "firing-uuid",
    "fired_at": "2025-01-20T12:00:00Z",
    "observed_value": "1042",
    "threshold_value": "1000",
    "period_started_at": "2025-01-01T00:00:00Z",
    "period_ends_at": "2025-02-01T00:00:00Z",
    "delivery_status": "delivered",
    "http_status": 200,
    "attempt_count": 1,
    "last_error": null,
    "payload": {
      "trigger_id": "trigger-uuid",
      "resource_type": "voice_call",
      "observed_value": "1042"
    }
  }
]

POST/usage/triggers/:trigger_id/firings/:firing_id/redeliver

Retenter la livraison webhook pour un déclenchement, en rejouant les octets originaux du payload.

Relancer un déclenchement

Retente la livraison webhook pour un seul déclenchement, rejouant le même payload. L'en-tête X-Aethex-Signature porte un nouvel horodatage et une nouvelle signature à chaque tentative. Met à jour la ligne d'audit existante plutôt que d'en insérer une nouvelle. Nécessite la portée usage:write.

Chemin & Requête

trigger_idstringrequis
UUID du déclencheur
firing_idstringrequis
UUID du déclenchement (depuis GET /usage/triggers/{trigger_id}/firings)

Erreurs

400Pas de secret webhook

Votre compte n'a pas de webhook_secret configuré, donc la relance ne peut pas être signée.

Appelez POST /usage/webhook-secret/rotate pour en générer un, puis réessayez.

401Non autorisé

Clé API manquante ou invalide.

Envoyez X-API-Key: YOUR_KEY.

403Interdit

La clé API n'a pas la portée usage:write.

Émettez une clé avec usage:write.

404Déclencheur ou déclenchement introuvable

Le déclencheur ou le déclenchement n'existe pas, ou l'un d'eux n'appartient pas au compte appelant.

Vérifiez les deux IDs via GET /usage/triggers et GET /usage/triggers/{trigger_id}/firings.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/usage/triggers/trigger-uuid/firings/firing-uuid/redeliver \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "firing-uuid",
  "fired_at": "2025-01-20T12:00:00Z",
  "observed_value": "1042",
  "threshold_value": "1000",
  "period_started_at": "2025-01-01T00:00:00Z",
  "period_ends_at": "2025-02-01T00:00:00Z",
  "delivery_status": "delivered",
  "http_status": 200,
  "attempt_count": 2,
  "last_error": null,
  "payload": {
    "trigger_id": "trigger-uuid",
    "resource_type": "voice_call",
    "observed_value": "1042"
  }
}