Pour commencer

API NumeroClaw

Une API workspace authentifiée avec un cycle asynchrone. Créez une lecture, suivez son état, puis récupérez le résultat ou les artefacts publiés.

Authentification

Envoyez votre clé API workspace dans l'en-tête x-api-key sur tous les endpoints : /api/v1/readings, /api/v1/readings/{id}, /api/v1/readings/{id}/result, /api/v1/readings/{id}/document et /api/v1/webhooks.

La plateforme accepte aussi des routes portal en bearer token, mais pour les intégrations publiques x-api-key reste la base recommandée.

curl https://api.numeroclaw.com/api/v1/readings \
  -H "x-api-key: YOUR_API_KEY"

Créer une lecture

Le produit public actuel est theme. Champs requis :

• productId — aujourd'hui theme
• profileId — aujourd'hui evan
• locale — fr-FR ou en-US
• name.firstNames — tableau requis
• name.middleNames — tableau, peut être vide
• name.lastNames — tableau requis
• dateOfBirth — YYYY-MM-DD strict
• grammaticalProfile.subjectGender — M ou F

curl -X POST https://api.numeroclaw.com/api/v1/readings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "productId": "theme",
    "profileId": "evan",
    "locale": "fr-FR",
    "name": {
      "firstNames": ["Marie-France"],
      "middleNames": ["Paulette"],
      "lastNames": ["Dubois"]
    },
    "dateOfBirth": "1990-03-15",
    "grammaticalProfile": { "subjectGender": "F" }
  }'

POST /api/v1/readings renvoie 201 Created avec une ressource de lecture, pas un texte final. L'état initial attendu est queued ou processing.

Cycle asynchrone

Modélisez la plateforme comme une machine à états.

N'inscrivez pas un délai universel fixe. Le temps de stabilisation peut varier selon la charge et le produit.

Polling

Sondez par readingId si vous n'utilisez pas les webhooks.

const baseUrl = 'https://api.numeroclaw.com';

async function numeroclaw(path) {
  const response = await fetch(baseUrl + path, {
    headers: { 'x-api-key': process.env.NUMEROCLAW_API_KEY },
  });

  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

async function waitForReading(readingId, { intervalMs = 10000, maxAttempts = 30 } = {}) {
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const reading = await numeroclaw('/api/v1/readings/' + readingId);

    if (reading.status === 'completed') {
      return numeroclaw('/api/v1/readings/' + readingId + '/result');
    }

    if (reading.status === 'failed') {
      throw new Error('NumeroClaw a marqué la lecture comme échouée.');
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }

  throw new Error('Lecture toujours non terminée. Augmentez le timeout ou passez aux webhooks.');
}

Webhooks

Enregistrez les webhooks sur la même surface workspace.

Endpoints

• GET /api/v1/webhooks
• POST /api/v1/webhooks
• PATCH /api/v1/webhooks/{endpointId}

Événements

• reading.completed
• reading.failed
• reading.published
• reading.delayed

La creation d'un webhook renvoie un signingSecret à usage initial. Les livraisons utilisent x-numeroclaw-signature et x-numeroclaw-timestamp. Format : t={unixTimestamp},v1={hexHmacSha256} sur {timestamp}.{rawBody}.

curl -X POST https://api.numeroclaw.com/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://your-app.example/webhooks/numeroclaw",
    "events": ["reading.published", "reading.failed"]
  }'

Récupération

Utilisez /result pour la surface stable cote client.

• GET /api/v1/readings/{readingId} — ressource workspace et état actuel.
• GET /api/v1/readings/{readingId}/result — résultat stabilisé, avec clientDocument et clientAccessUrl.
• GET /api/v1/readings/{readingId}/document — artefact publié au format demandé.

curl https://api.numeroclaw.com/api/v1/readings/READING_ID/result \
  -H "x-api-key: YOUR_API_KEY"

Formats de sortie

Le produit Thème publie trois artefacts après complétion :

• document_v1 — document JSON structuré
• markdown — rendu text/markdown
• pdf — document PDF binaire

curl "https://api.numeroclaw.com/api/v1/readings/READING_ID/document?format=markdown" \
  -H "x-api-key: YOUR_API_KEY"

Erreurs

Intégration

Prêt à copier-coller pour n'importe quelle surface. Choisissez votre environnement, prenez le snippet, et c'est en ligne.

curl -X POST https://api.numeroclaw.com/api/v1/readings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "productId": "theme",
    "profileId": "evan",
    "locale": "fr-FR",
    "name": {
      "firstNames": ["Marie-France"],
      "middleNames": ["Paulette"],
      "lastNames": ["Dubois"]
    },
    "dateOfBirth": "1990-03-15",
    "grammaticalProfile": { "subjectGender": "F" }
  }'

import requests

resp = requests.post(
    "https://api.numeroclaw.com/api/v1/readings",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "productId": "theme",
        "profileId": "evan",
        "locale": "fr-FR",
        "name": {
            "firstNames": ["Marie-France"],
            "middleNames": ["Paulette"],
            "lastNames": ["Dubois"]
        },
        "dateOfBirth": "1990-03-15",
        "grammaticalProfile": {"subjectGender": "F"}
    }
)
reading_id = resp.json()["id"]
# Pollez GET /api/v1/readings/{reading_id} jusqu'à status "completed"

const res = await fetch("https://api.numeroclaw.com/api/v1/readings", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    productId: "theme",
    profileId: "evan",
    locale: "fr-FR",
    name: {
      firstNames: ["Marie-France"],
      middleNames: ["Paulette"],
      lastNames: ["Dubois"]
    },
    dateOfBirth: "1990-03-15",
    grammaticalProfile: { subjectGender: "F" }
  })
});
const { id } = await res.json();
// Pollez GET /api/v1/readings/{id} jusqu'à status "completed"

Génère une lecture de numérologie avec l'API NumeroClaw.

POST https://api.numeroclaw.com/api/v1/readings
Header: x-api-key: YOUR_API_KEY
Header: Content-Type: application/json

Body:
{
  "productId": "theme",
  "profileId": "evan",
  "locale": "fr-FR",
  "name": {
    "firstNames": ["Marie-France"],
    "middleNames": ["Paulette"],
    "lastNames": ["Dubois"]
  },
  "dateOfBirth": "1990-03-15",
  "grammaticalProfile": { "subjectGender": "F" }
}

Pollez GET /api/v1/readings/{id} jusqu'à status "completed".
Récupérez le résultat depuis GET /api/v1/readings/{id}/result.

Tu as accès à l'API NumeroClaw pour générer des lectures de
numérologie professionnelles.

Endpoint : POST https://api.numeroclaw.com/api/v1/readings
Auth :     x-api-key: YOUR_API_KEY
Produit :  "theme" (thème numérologique personnel complet, 20 crédits)
Locales :  "fr-FR" ou "en-US"

Quand un utilisateur demande une lecture de numérologie, collecte :
- Le nom complet de naissance (prénom, second prénom, nom)
- La date de naissance (AAAA-MM-JJ)
- Le genre (M ou F, pour l'accord grammatical)
- La langue préférée

Appelle l'API, puis poll GET /api/v1/readings/{id}
jusqu'à status "completed".
Renvoie la lecture depuis GET /api/v1/readings/{id}/result.

NumeroClaw CLI

numeroclaw create        # création interactive guidée
numeroclaw batch run f.csv  # traiter un CSV de lectures
numeroclaw doctor        # diagnostiquer config + connectivite

Tableau de bord NumeroClaw

Exemples de sortie

Lectures complètes générées par l'API. Cliquez sur une carte pour ouvrir la lecture publiée.

Surfaces lisibles par machine

• /llms.txt — découverte légère
• /llms-full.txt — docs API complètes pour pipelines RAG
• /docs/reference.fr.md — corpus Markdown complet
• /rss.xml — flux mises à jour produit
• /robots.txt — directives crawlers
• /sitemap.xml — sitemap avec hreflang