# Angel Numbers API, what to build and how to call it

> Ship an angel-number lookup tool, a daily number widget, or a detector for repeating sequences in under 15 minutes.

`111 meaning`, `222 meaning`, `333 angel number` are evergreen viral queries. Gen Z spiritual-tok keeps them trending. The Roxy angel-number endpoints cover the 43 canonical sequences plus a universal lookup that works for any positive integer via digit-root fallback. Users never hit "not found".

## What you can build

- Angel-number meaning pages (every "meaning of 1111" URL backs to this)
- Detectors that spot repeating numbers on clocks and receipts
- Daily angel-number widgets with affirmations
- Spiritual chatbots that interpret any number sequence

## Prerequisites

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. Nothing else. Content is pure GET.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## Call the endpoint

The #1 call is the universal lookup. It accepts any positive integer and always returns something meaningful. Pick a language.


### curl
```bash
curl "https://roxyapi.com/api/v2/angel-numbers/lookup?number=444" \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK
```typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.angelNumbers.analyzeNumberSequence({
  query: { number: '444' },
});

const meaning = data.knownMeaning ?? data.digitRootMeaning;
console.log(meaning.title);
console.log(meaning.coreMessage);
```

### Python SDK
```python
import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

result = roxy.angel_numbers.analyze_number_sequence(number='444')
meaning = result.get('knownMeaning') or result['digitRootMeaning']
print(meaning['title'])
print(meaning['coreMessage'])
```

### PHP SDK
```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$result = $roxy->angelNumbers->analyzeNumberSequence(number: '444');
$meaning = $result['knownMeaning'] ?? $result['digitRootMeaning'];
echo $meaning['title'];
echo $meaning['coreMessage'];
```

### MCP
```bash
claude mcp add-json --scope user roxy-angel '{"type":"http","url":"https://roxyapi.com/mcp/angel-numbers","headers":{"X-API-Key":"YOUR_KEY"}}'
```

Then ask Claude, "what does seeing 444 mean?" The agent calls the lookup tool. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

The response includes `number`, `type` (repeating, sequential, mirror, master, root), `digitRoot`, `isPalindrome`, `isRepeating`, a `knownMeaning` block (present when the number is one of the 43 canonical sequences) and a `digitRootMeaning` fallback (always present). Each meaning block has `title`, `coreMessage`, `energy`, `keywords`, `affirmation`, `actionSteps`, and a nested `meaning` sub-object with `love`, `career`, `spiritual`, `twinFlame`. Use `knownMeaning ?? digitRootMeaning` to read the same fields regardless of which is set.

## Render the result

Use the generic `<roxy-data>` renderer from [`@roxyapi/ui`](/docs/ui), exposed in React as `RoxyData`. It accepts any RoxyAPI response and lays out the JSON for you, including the nested `knownMeaning` and `digitRootMeaning` blocks, with no per-field markup. Pass the unwrapped `data` straight in.

```tsx
'use client';
import { RoxyData } from '@roxyapi/ui-react';
import type { GetAngelNumbersLookupResponse } from '@roxyapi/sdk';

export function AngelNumberCard({ data }: { data: GetAngelNumbersLookupResponse }) {
  return <RoxyData data={data} />;
}
```

`data` is the unwrapped SDK response (`const { data } = await roxy.angelNumbers.analyzeNumberSequence(...)`), typed by `GetAngelNumbersLookupResponse` from `@roxyapi/sdk`.

## Ship the rest

### Specific number

[`GET /angel-numbers/numbers/{number}`](/api-reference#tag/angel-numbers/GET/angel-numbers/numbers/{number}) returns the full interpretation when the number is a canonical angel sequence (1111, 222, 777, etc.). Use this for SEO landing pages that map one URL per number.

### Daily

[`POST /angel-numbers/daily`](/api-reference#tag/angel-numbers/POST/angel-numbers/daily) returns a daily angel number with optional per-user `seed` for deterministic push notifications.

See the full list at the [Angel Numbers API reference](/api-reference#tag/angel-numbers).

## Ready-made starter

The [/starters/astrology-ai-chatbot](/starters/astrology-ai-chatbot) (multi-domain, covers Angel Numbers via Remote MCP) starter ships a working Angel Numbers app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, see the component catalog in [@roxyapi/ui](/docs/ui).

## Gotchas

- **The lookup endpoint works for any positive integer.** Digit-root fallback covers non-canonical numbers. Do not write validation logic that rejects non-111/222/333 patterns.
- **Numbers are strings in paths, integers in the lookup query.** `/numbers/1111` path takes a string, `/lookup?number=444` query param is the same. Pass strings to be safe.
- **`type` is the pattern classifier.** `repeating` (444), `sequential` (123), `mirror` (121), `master` (11), `root` (9). Use this to theme the UI.
- **`lang` controls translation.** Pass `?lang=fr` for French meanings, 8 languages supported.

## What to build next

For a multi-domain spiritual chatbot, the [AI chatbot tutorial](/docs/tutorials/ai-chatbot) wires angel numbers plus tarot plus numerology under one agent. For typed calls, the [SDK guide](/docs/sdk).