# NumeroClaw — Complete API Documentation

> NumeroClaw is an async numerology API that generates premium, personalized numerological readings for developers, AI agents, wellness brands, and content creators. Base URL: https://api.numeroclaw.com. This document contains the complete API reference for LLM ingestion.

Last updated: 2026-04-06

---

## Overview

NumeroClaw is an authenticated workspace API with an async lifecycle. Create a reading, track status, then fetch the result or published artifacts when ready.

- Base URL: https://api.numeroclaw.com
- Current product: `theme`
- Supported locales: `fr-FR`, `en-US`
- Cost: 20 credits per theme reading

**Important:** NumeroClaw is NOT a synchronous API. You cannot get a completed reading in a single call. You must create the reading, poll for status or register a webhook, then retrieve the result when complete.

---

## Authentication

Send your workspace API key in the `x-api-key` header on all endpoints:

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

Supported endpoints:
- `/api/v1/readings`
- `/api/v1/readings/{id}`
- `/api/v1/readings/{id}/result`
- `/api/v1/readings/{id}/document`
- `/api/v1/webhooks`

The platform also supports bearer-authenticated portal routes, but for public integrations `x-api-key` is the recommended default.

---

## Create a Reading

The current public product is `theme`. Required request fields:

- `productId` — currently `theme`
- `profileId` — currently `evan`
- `locale` — `fr-FR` or `en-US`
- `name.firstNames` — required array of strings
- `name.middleNames` — array of strings (can be empty)
- `name.lastNames` — required array of strings
- `dateOfBirth` — strict `YYYY-MM-DD` format
- `grammaticalProfile.subjectGender` — `M` or `F`

### Example Request

```
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": "en-US",
    "name": {
      "firstNames": ["Marie-France"],
      "middleNames": ["Paulette"],
      "lastNames": ["Dubois"]
    },
    "dateOfBirth": "1990-03-15",
    "grammaticalProfile": { "subjectGender": "F" }
  }'
```

`POST /api/v1/readings` returns `201 Created` with a reading resource, not a finished reading body. Expect `status` to begin as `queued` or `processing`.

---

## Async Lifecycle

Model the platform as a state machine:

| Status | Meaning | Action |
|--------|---------|--------|
| `queued` | Accepted, waiting for processing | Keep `readingId`, poll or await webhook |
| `processing` | Generation is underway | Continue polling or wait for webhook |
| `completed` | Reading finished successfully | Fetch `/result` or published formats |
| `failed` | Reading failed with error payload | Inspect `error.code` and decide retry |

Do not hardcode a universal completion window. Different products and workloads may settle on different timing.

---

## Polling

Poll by reading ID when webhooks are not available:

```javascript
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 marked the reading as failed.');
    }
    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }
  throw new Error('Reading still not complete. Increase timeout or switch to webhooks.');
}
```

---

## Webhooks

Register webhooks on the same workspace surface.

### Endpoints

- `GET /api/v1/webhooks` — list registered webhooks
- `POST /api/v1/webhooks` — create a new webhook
- `PATCH /api/v1/webhooks/{endpointId}` — update a webhook

### Event Types

- `reading.completed` — reading finished successfully
- `reading.failed` — reading generation failed
- `reading.published` — reading artifacts are published and available
- `reading.delayed` — reading is taking longer than expected

### Webhook Security

Webhook creation returns a one-time `signingSecret`. Deliveries are signed with `x-numeroclaw-signature` and `x-numeroclaw-timestamp`. Format: `t={unixTimestamp},v1={hexHmacSha256}` over `{timestamp}.{rawBody}`.

### Example: Register a Webhook

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

---

## Reading Retrieval

Use `/result` for the stable client-facing payload.

- `GET /api/v1/readings/{readingId}` — workspace reading resource and current status
- `GET /api/v1/readings/{readingId}/result` — stable result, including `clientDocument` and `clientAccessUrl`
- `GET /api/v1/readings/{readingId}/document` — published artifact in the requested format

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

---

## Output Formats

The Theme product publishes three artifacts after completion:

- `document_v1` — structured JSON document
- `markdown` — text/markdown rendition
- `pdf` — binary PDF document

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

---

## Errors

| Status | Meaning |
|--------|---------|
| `400` | Invalid request body, unsupported locale, invalid webhook URL, or unknown product/profile |
| `401` | Missing or invalid workspace authentication |
| `402` | Insufficient credits for the requested reading |
| `403` | Resource belongs to a different workspace, or a portal-only route rejected the auth mode |
| `404` | Reading, document, or webhook endpoint not found |
| `429` | Rate limit exceeded. Respect `Retry-After` when present |
| `503` | Temporary platform issue such as enqueue or billing configuration failure |

---

## Integration Examples

### curl

```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": "en-US",
    "name": {
      "firstNames": ["Marie-France"],
      "middleNames": ["Paulette"],
      "lastNames": ["Dubois"]
    },
    "dateOfBirth": "1990-03-15",
    "grammaticalProfile": { "subjectGender": "F" }
  }'
```

### Python

```python
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": "en-US",
        "name": {
            "firstNames": ["Marie-France"],
            "middleNames": ["Paulette"],
            "lastNames": ["Dubois"]
        },
        "dateOfBirth": "1990-03-15",
        "grammaticalProfile": {"subjectGender": "F"}
    }
)
reading_id = resp.json()["id"]
# Poll GET /api/v1/readings/{reading_id} until status is "completed"
```

### JavaScript

```javascript
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: "en-US",
    name: {
      firstNames: ["Marie-France"],
      middleNames: ["Paulette"],
      lastNames: ["Dubois"]
    },
    dateOfBirth: "1990-03-15",
    grammaticalProfile: { subjectGender: "F" }
  })
});
const { id } = await res.json();
// Poll GET /api/v1/readings/{id} until status is "completed"
```

### Claude Code / AI Agent Prompt

```
Generate a numerology reading using the NumeroClaw API.

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": "en-US",
  "name": {
    "firstNames": ["Marie-France"],
    "middleNames": ["Paulette"],
    "lastNames": ["Dubois"]
  },
  "dateOfBirth": "1990-03-15",
  "grammaticalProfile": { "subjectGender": "F" }
}

Poll GET /api/v1/readings/{id} until status is "completed".
Then fetch the result from GET /api/v1/readings/{id}/result.
```

---

## Pricing

| Plan | Monthly Price | Credits | Per Reading |
|------|--------------|---------|-------------|
| Starter | $49/mo | 200 credits | ~10 readings |
| Growth | $190/mo | 1,000 credits | ~50 readings |
| Scale | $490/mo | 3,000 credits | ~150 readings |
| Enterprise | $1,190/mo | 10,000 credits | ~500 readings |

Each Theme reading costs 20 credits. All plans include API access, both locales, all output formats, and webhook support.

---

## Product Roadmap

Currently shipped: Personal Theme. Coming soon: Year Forecast, Compatibility Reading, Name Analysis, Monthly Forecast, Karmic Profile, Birthday Portrait, Life Cycles, Business Numerology, Child Profile.

---

## Links

- Website: https://numeroclaw.com
- App / Dashboard: https://app.numeroclaw.com
- API Base URL: https://api.numeroclaw.com
- Docs: https://numeroclaw.com/docs/
- Samples: https://numeroclaw.com/examples/
- RSS Feed: https://numeroclaw.com/rss.xml
- Contact: hello@numeroclaw.com