Getting started

NumeroClaw API

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

Authentication

Send your workspace API key in the x-api-key header on all endpoints: /api/v1/readings, /api/v1/readings/{id}, /api/v1/readings/{id}/result, /api/v1/readings/{id}/document, and /api/v1/webhooks.

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

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

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
• name.middleNames — array, can be empty
• name.lastNames — required array
• dateOfBirth — strict YYYY-MM-DD
• grammaticalProfile.subjectGender — M or 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": "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.

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.

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
• POST /api/v1/webhooks
• PATCH /api/v1/webhooks/{endpointId}

Event types

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

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}.

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

Integrate

Copy-paste ready for any surface. Pick your runtime, grab the snippet, and you're live.

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

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"

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"

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": "fr-FR",
  "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.

You have access to the NumeroClaw API for generating professional
numerology readings.

Endpoint: POST https://api.numeroclaw.com/api/v1/readings
Auth:     x-api-key: YOUR_API_KEY
Product:  "theme" (complete personal numerology theme, 20 credits)
Locales:  "fr-FR" or "en-US"

When a user asks for a numerology reading, collect:
- Full birth name (first, middle, last)
- Date of birth (YYYY-MM-DD)
- Gender (M or F, for grammatical agreement)
- Preferred language

Call the API, then poll GET /api/v1/readings/{id}
until status is "completed".
Return the reading from GET /api/v1/readings/{id}/result.

NumeroClaw CLI

numeroclaw create        # guided interactive creation
numeroclaw batch run f.csv  # process a CSV of readings
numeroclaw doctor        # diagnose config + connectivity

NumeroClaw Dashboard

Sample output

Full readings generated by the API. Click a card to open the published reading.

Machine-readable surfaces

• /llms.txt — lightweight agent discovery
• /llms-full.txt — complete API docs for RAG pipelines
• /docs/reference.md — full Markdown corpus
• /rss.xml — product updates feed
• /robots.txt — crawler directives
• /sitemap.xml — sitemap with hreflang