# Référence API NumeroClaw

Date de lancement : 2026-04-04

NumeroClaw doit être modélisé comme une API de lecture asynchrone authentifiée.

## Base URL

`https://api.numeroclaw.com`

## Produit public actuel

- `productId` : `theme`
- `profileId` : `evan`
- Langues publiques actuelles : `fr-FR`, `en-US`
- Artefacts publics actuels : `document_v1`, `markdown`, `pdf`
- Coût d’un Thème Standard : 20 crédits

## Authentification

Le chemin public le plus clair est la clé API workspace :

- En-tête : `x-api-key: YOUR_API_KEY`

La plateforme accepte aussi des tokens bearer sur certaines routes portal, mais `x-api-key` reste la base publique la plus simple et la plus honnête.

## Créer une lecture

Endpoint :

- `POST /api/v1/readings`

Exemple :

```bash
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" }
  }'
```

Champs requis :

- `productId`
- `profileId`
- `locale`
- `name.firstNames`
- `name.middleNames`
- `name.lastNames`
- `dateOfBirth`
- `grammaticalProfile.subjectGender`

Notes :

- `dateOfBirth` doit être strictement au format `YYYY-MM-DD`
- `name` doit utiliser des tableaux structurés de noms de naissance
- le support public actuel est limité au français et à l’anglais

Exemple de réponse acceptée :

```json
{
  "readingId": "9d38d8f5-1a2b-4f70-9b4a-4df9f0a4d131",
  "workspaceId": "workspace_demo",
  "status": "queued",
  "productId": "theme",
  "profileId": "evan",
  "locale": "fr-FR",
  "input": {
    "name": {
      "firstNames": ["Marie-France"],
      "middleNames": ["Paulette"],
      "lastNames": ["Dubois"]
    },
    "displayName": "Marie-France Paulette Dubois",
    "dateOfBirth": "1990-03-15",
    "grammaticalProfile": { "subjectGender": "F" }
  },
  "document": {
    "available": false,
    "version": null,
    "artifactId": null,
    "publishedAt": null
  },
  "error": null
}
```

## Cycle asynchrone

NumeroClaw ne promet pas un délai universel fixe.

États publics :

- `queued`
- `processing`
- `completed`
- `failed`

Forme recommandée d’intégration :

1. Créer la lecture avec `POST /api/v1/readings`
2. Stocker `readingId`
3. Sonder `GET /api/v1/readings/{readingId}` ou attendre un webhook
4. Récupérer `GET /api/v1/readings/{readingId}/result` une fois terminé
5. Tirer les formats publiés via `GET /api/v1/readings/{readingId}/document`

## Polling

Endpoint d’état :

- `GET /api/v1/readings/{readingId}`

Endpoint de résultat stable :

- `GET /api/v1/readings/{readingId}/result`

Exemple :

```js
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 votre timeout ou passez aux webhooks.');
}
```

## Webhooks

Endpoints de gestion :

- `GET /api/v1/webhooks`
- `POST /api/v1/webhooks`
- `PATCH /api/v1/webhooks/{endpointId}`

Événements supportés :

- `reading.completed`
- `reading.failed`
- `reading.published`
- `reading.delayed`

Exemple de création :

```bash
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"]
  }'
```

Sécurité :

- la création renvoie un `signingSecret` initial
- les livraisons envoient :
  - `x-numeroclaw-event`
  - `x-numeroclaw-timestamp`
  - `x-numeroclaw-signature`
- format de signature : `t={unixTimestamp},v1={hexHmacSha256}`
- donnée signée : `{timestamp}.{rawBody}`

## Récupération

Ressource workspace :

- `GET /api/v1/readings/{readingId}`

Résultat stable :

- `GET /api/v1/readings/{readingId}/result`

Document publié :

- `GET /api/v1/readings/{readingId}/document?format=document_v1`
- `GET /api/v1/readings/{readingId}/document?format=markdown`
- `GET /api/v1/readings/{readingId}/document?format=pdf`

## Formats

Le produit Theme publie aujourd’hui :

- `document_v1`
- `markdown`
- `pdf`

La requête de création publique ne demande pas actuellement au client de choisir le format à la soumission.

## Erreurs

Erreurs publiques les plus courantes :

- `400` : corps invalide, locale non supportée, produit/profil inconnu, URL webhook invalide
- `401` : authentification workspace absente ou invalide
- `402` : crédits insuffisants
- `403` : mauvais workspace ou mauvais mode d’auth pour la route
- `404` : lecture, document ou endpoint webhook introuvable
- `429` : rate limit dépassée, respecter `Retry-After`
- `503` : incident temporaire file d’attente ou facturation

## Tarifs et crédits

Logique actuelle :

- `theme` coûte 20 crédits
- Studio : 400 crédits / mois / 149 $
- Pro : 2 000 crédits / mois / 399 $
- Growth : 10 000 crédits / mois / 1 190 $
- Access Local : 100 crédits / mois / 49 $, plan régional revu

Packs publics actuels :

- Flex : 50 crédits / 29 $
- Sprint : 200 crédits / 99 $
- Campaign : 500 crédits / 199 $
- Burst : 2 000 crédits / 699 $

## Exemples

- Échantillon FR : `/examples/messi-fr.md`
- Aperçu EN de lancement : `/examples/messi-en.md`
- Page exemples : `/fr/examples/`

## Surfaces machine-readable

- `/llms.txt`
- `/lm.txt`
- `/docs/reference.md`
- `/rss.xml`