API documentation

NumeroClaw API

Create Theme, Birthday Portrait, and Name Analysis readings from one authenticated workspace API. Creation is asynchronous: submit a validated request, keep the returned readingId, then retrieve the result or receive a webhook.

Authentication

Create a workspace key in Developers → API keys, then send it in the x-api-key header. The complete key begins with numk_live_ and is shown only once.

curl https://api.numeroclaw.com/api/v1/usage \
  -H "x-api-key: $NUMEROCLAW_API_KEY"

Product catalogue

Read the public catalogue resource before building a form or confirming a charge. It returns the current credit cost, input rules, profiles, locale, output formats, catalogue version, and catalogue hash. This endpoint is the integration source of truth.

GET /api/v1/catalog/products/theme
GET /api/v1/catalog/products/birthday-portrait
GET /api/v1/catalog/products/name-analysis

These routes do not require authentication. Public money prices come only from purchasable offers in commercial-catalogue.json; do not infer them from credit cost.

Create a reading

Send POST /api/v1/readings. Include a unique Idempotency-Key whenever a client or job may retry the same submission. A successful request returns HTTP 201 and readingId.

curl -X POST https://api.numeroclaw.com/api/v1/readings \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NUMEROCLAW_API_KEY" \
  -H "Idempotency-Key: your-stable-request-id" \
  -d @confirmed-reading.json

The exact product cost is debited when the request is accepted. NumeroClaw compensates the debit if enqueueing or generation fails terminally.

Theme request

A Theme connects a structured birth name and date of birth. subjectGender controls grammatical language only.

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

Birthday Portrait request

A Birthday Portrait requires only the date of birth. firstName is optional and presentation-only; it does not change the calculation.

{
  "productId": "birthday-portrait",
  "profileId": "birthday-portrait-v1",
  "locale": "en-US",
  "dateOfBirth": "1990-03-15",
  "firstName": "Marie-France"
}

Name Analysis request

Name Analysis uses the complete birth name and does not require a date of birth or gender. A current-use name is optional. When supplied, currentNameContext is required.

{
  "productId": "name-analysis",
  "profileId": "name-analysis-v1",
  "locale": "en-US",
  "birthName": {
    "firstNames": ["Clara"],
    "middleNames": [],
    "lastNames": ["Moreau"]
  },
  "currentName": {
    "firstNames": ["Clara"],
    "middleNames": [],
    "lastNames": ["Martin"]
  },
  "currentNameContext": {
    "contexts": ["professional", "social"],
    "scope": "frequent",
    "usedSinceYear": 2018
  }
}

Contexts: professional, social, legal, household, other. Scope: primary, frequent, context-specific, occasional.

Shared and conditional fields

• locale may be omitted and defaults to en-US. New creation is English-only.
• dateOfBirth must be a real date in strict YYYY-MM-DD format.
• openingNote is optional, presentation-only, and limited to 280 characters.
• brandSnapshot can apply NumeroClaw or custom branding, contact details, colors, logo data, cover style, and footer text.
• metadata may carry integration context.
• If a Theme or Name Analysis name contains Y, classify every occurrence through yClassifications; validation identifies the required path and index.

Async lifecycle

Creation and status responses may include generationEstimate with estimated start, completion, and remaining seconds. It is an estimate, not a service guarantee.

const created = await response.json();
const readingId = created.readingId; // not created.id

Readings and documents

• GET /api/v1/readings?status=completed&limit=50&offset=0 — list workspace readings.
• GET /api/v1/readings/{readingId} — current status and metadata.
• GET /api/v1/readings/{readingId}/result — stable result and access URL when published.
• DELETE /api/v1/readings/{readingId} — delete an owned reading once it is no longer queued or processing.

Retrieve the product’s canonical JSON version, markdown, or pdf:

GET /api/v1/readings/{readingId}/document?format=document_v1
GET /api/v1/readings/{readingId}/document?format=document_v2
GET /api/v1/readings/{readingId}/document?format=document_v3
GET /api/v1/readings/{readingId}/document?format=pdf&download=1

download=1 returns an attachment. document_v1 remains a compatibility alias, but new integrations should request the canonical version for their product.

Webhooks

Use GET|POST /api/v1/webhooks and PATCH /api/v1/webhooks/{endpointId}. A workspace may have up to ten active endpoints. Events: reading.completed, reading.failed, reading.published, and reading.delayed.

The create response shows signingSecret once. Verify x-numeroclaw-signature as HMAC-SHA256 over {timestamp}.{rawBody}. The header format is t={timestamp},v1={hexDigest}.

Usage, keys, and credits

• GET /api/v1/usage?period=24h|7d|30d|90d — usage summary.
• GET|POST /api/v1/api-keys — list or create keys.
• POST /api/v1/api-keys/{apiKeyId}/revoke — revoke a key.

All products use one workspace balance. Capability and output quality do not change with purchase volume; only the effective price per credit may change.

Errors

Personal agents (MCP)

Personal AI agents can buy and generate a reading for someone who has no NumeroClaw account. The connector is a remote MCP server over Streamable HTTP; no API key and no sign-up are required.

create_order validates the person’s details, charges nothing, and returns an order token with a paymentLink. An agent POSTs that link and receives an HTTP 402 Machine Payments challenge it pays with a Stripe Link shared payment token; opening the same link in a browser shows Stripe Checkout instead. Nothing is charged until the person approves the amount.

After payment, poll get_order until it returns reading.clientAccessUrl, the private link to the finished reading and its PDF. Unpaid orders expire after 24 hours.

Payment is taken at purchase and the reading is written afterwards. A reading is usually ready well under an hour, and at busy times it can take up to 6 hours; get_order returns a live estimate alongside the status, so an agent can tell the person when to expect it. Poll about every 60 seconds for the first 10 minutes, then every 5 minutes.

If a paid reading cannot be produced, get_order reports the order as failed and the payment is refunded: NumeroClaw is notified and reviews each refund before issuing it, after which it usually reaches the payment method within a few business days.

For Theme, each letter Y in the birth name needs a vowel or consonant sound: the agent works out each one from the name and reads it back to the person to confirm, because the classification changes the numbers and NumeroClaw never guesses it.

Machine-readable documentation

• /docs/reference.md — complete Markdown API reference
• /llms.txt — concise agent discovery
• /llms-full.txt — consolidated LLM and retrieval corpus
• /commercial-catalogue.json — public commercial projection
• /agent-setup/prompt.md — safe agent setup