Getting started

NumeroClaw Theme API

An authenticated workspace API with an async lifecycle. Create a Theme, track its 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 — 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 assume one-minute delivery. A Theme can take up to a few hours because generation and artifact work are asynchronous. A completed status does not mean the current architecture has passed the new product quality gate.

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 = 30000, maxAttempts = 480 } = {}) {
  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"

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)
Locale:   "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)

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 Dashboard

Rejected historical output

These previous-architecture Themes failed the new benchmark. They remain available for transparency and regression review, not as current quality samples.

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