Documentation API · v1

L'Algorithme API

Mémoire vectorielle interrogeable en langage naturel. Ingérez des faits, construisez un profil, obtenez un signal.

Vue d'ensemble

L'API repose sur trois primitives :

Ingestion

Envoyez un fait — un contexte et une valeur. L'Algorithme les vectorise et les intègre dans la mémoire de l'utilisateur.

Mémoire

Chaque fait s'accumule avec un poids EMA. Les faits redondants fusionnent ; les faits contradictoires coexistent pondérés.

Signal

Interrogez la mémoire avec un contexte et des candidats. L'API retourne une probabilité par candidat — sans règles, sans schéma.

Base URLhttps://algorithme.athenox.dev

Authentification

Toutes les routes requièrent une clé API transmise en header HTTP.

Header

Authorization: Bearer alg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Générez votre clé depuis le tableau de bord après connexion KonnectID. La clé n'est affichée qu'une seule fois.

La clé est scopée à votre user_id. Elle ne peut accéder qu'à vos propres données.

Entity ID

L'Algorithme ne vous impose aucun format d'identifiant. Utilisez ce qui vous convient : un entier, un UUID, un email, un slug, un hash.

Exemples d'entity ID valides

/api/users/42/facts
/api/users/user@example.com/facts
/api/users/a1b2c3d4-e5f6-7890/facts
/api/users/jean-dupont/facts

L'entité est créée automatiquement au premier appel POST /facts. Pas besoin de l'enregistrer au préalable.

Une clé API peut accéder à une entité uniquement si elle y a ingéré au moins un fait. L'accès est accordé automatiquement à la première ingestion.

Chaque clé API est isolée : deux clés différentes ne voient pas les mêmes entités, même si elles utilisent les mêmes identifiants.

Ingérer un fait

POST/api/users/{user_id}/facts

Ingère un fait dans la mémoire de l'utilisateur. Le contexte et la valeur sont tous deux vectorisés par le modèle d'embedding.

Corps de la requête

Champ	Type	Requis	Description
`context`	string	oui	Contexte sémantique du fait (ex : "préférence couleur")
`value`	string	oui	Valeur associée (ex : "bleu marine")

Exemple

curl

curl -X POST https://algorithme.athenox.dev/api/users/{user_id}/facts \
  -H "Authorization: Bearer alg_..." \
  -H "Content-Type: application/json" \
  -d '{"context": "sport pratiqué", "value": "trail running"}'

Réponse 200

{
  "fact_id": 42,
  "user_id": "{user_id}"
}

Lister les faits

GET/api/users/{user_id}/facts

Retourne tous les faits en mémoire pour l'utilisateur. Les vecteurs ne sont pas exposés — seulement les métadonnées.

Réponse 200

[
  { "id": 42, "weight": 2.341, "owner_key": "sha256hash..." },
  { "id": 43, "weight": 1.000, "owner_key": "sha256hash..." }
]

weight reflète l'accumulation EMA — plus un fait est renforcé, plus son poids croît. Les faits redondants fusionnent automatiquement.

Interroger la mémoire

POST/api/users/{user_id}/query

Interroge la mémoire vectorielle et retourne un score de probabilité par candidat, basé sur les faits accumulés.

Corps de la requête

Champ	Type	Requis	Description
`context`	string	oui	Contexte de la requête en langage naturel
`candidates`	string[]	oui	Liste des candidats à scorer (2–20 recommandé)

Exemple

curl

curl -X POST https://algorithme.athenox.dev/api/users/{user_id}/query \
  -H "Authorization: Bearer alg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "context": "quel sport pratique cet utilisateur ?",
    "candidates": ["cyclisme", "natation", "trail running", "football"]
  }'

Réponse 200

{
  "probs": {
    "cyclisme":     0.08,
    "natation":     0.11,
    "trail running": 0.74,
    "football":     0.07
  },
  "confidence": 0.82,
  "reliable": true
}

Champs de réponse

Champ	Type	Description
`probs`	Record<string, number>	Probabilité par candidat, somme ≈ 1
`confidence`	number 0–1	Niveau de certitude global du signal
`reliable`	boolean	Signal exploitable (seuil de confiance atteint)

Supprimer

DELETE/api/users/{user_id}/facts/{fact_id}

Supprime un fait spécifique. Seule la clé qui a créé le fait peut le supprimer.

DELETE/api/users/{user_id}/facts

Supprime tous les faits créés par votre clé pour cet utilisateur.

Scoring vectoriel

Le moteur sémantique repose sur un modèle d'embedding entraîné et éprouvé par Korollr (BGE-m3, 1024 dimensions). Chaque fait ingéré produit deux vecteurs :

ctx_vec — vecteur du contexte (routage sémantique)
val_vec — vecteur de la valeur (contenu)

À la requête, le contexte est vectorisé et chaque candidat l'est aussi. Le score combine similarité contextuelle et similarité de valeur, pondéré par le poids EMA de chaque fait.

Plus vous ingérez de faits cohérents, plus le signal est précis. Le système converge sans configuration.

Erreurs

Code HTTP	Cause
`400`	Corps invalide — champ manquant ou mauvais type
`401`	Clé API absente ou invalide
`403`	Clé non autorisée sur ce user_id
`404`	Utilisateur ou fait introuvable
`500`	Erreur serveur — contacter contact@athenox.dev