# Angel Numbers API

> Production-ready angel numbers API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Look up meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 40+ angel number sequences. Includes love, career, spiritual, and twin flame interpretations per number. Smart lookup analyzes any number sequence with pattern detection, digit root calculation, and classification. Daily angel number endpoint, filter by type (repeating, sequential, mirror, master). Built for synchronicity apps, spiritual journals, daily guidance features, AI chatbots, and wellness platforms.

The first developer API for angel numbers. Ship a synchronicity app this weekend.

- Product page: https://roxyapi.com/products/angel-numbers-api
- OpenAPI spec: https://roxyapi.com/api/v2/angel-numbers/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/angel-numbers
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 4

## Features

- Complete angel number database covering triple repeating (111-999), quad repeating (1111-9999), double digits (11-99), mirror numbers, and sequential patterns with authoritative interpretations
- Four life area interpretations per number: love and relationships, career and finances, spiritual growth, and twin flame connections for comprehensive readings
- Smart lookup endpoint analyzes ANY number sequence with automatic pattern detection, digit root calculation, type classification, and matching to known angel number meanings
- Daily angel number endpoint returns a deterministic angel number based on date, perfect for daily guidance features, push notifications, and content generation
- Filter and browse by category: repeating numbers, sequential patterns, mirror numbers, master numbers, and root digits for building custom angel number explorers
- Actionable guidance per number: core message summary, positive affirmation, and 3-5 specific action steps to take when you see the number
- Keywords and energy classification (positive, neutral, cautionary) per number for quick filtering, search, and mood-based content generation
- AI-optimized structured JSON responses with rich descriptions perfect for chatbot integration, LLM consumption, and MCP tool calls
- Numerology digit root connection links each angel number to its foundational single-digit meaning for deeper analysis and cross-referencing with numerology data
- Sub-20ms response times for instant angel number interpretations at any scale
- MCP server and llms.txt ready: angel number lookups work as AI agent tool calls out of the box for chatbots, spiritual assistants, and multi-agent systems
- Zero domain expertise required: ship an angel numbers feature in your app without studying numerology or spiritual traditions
- Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter

## Use Cases

- Synchronicity tracking apps and spiritual journals: let users log angel number sightings and instantly see meanings, patterns, and guidance for personal growth and spiritual awareness
- AI chatbots and spiritual assistants: integrate angel number lookups into conversational AI, ChatGPT plugins, and virtual spiritual advisors with structured love, career, and spiritual readings
- Daily guidance and notification features: power daily angel number widgets, push notifications, and content feeds in wellness apps, meditation apps, and lifestyle platforms
- Dating and relationship apps: add angel number compatibility features, twin flame insights, and love guidance based on number sequences users encounter together
- Content generation systems: power angel number blog posts, social media content, and personalized email campaigns with accurate interpretations and SEO-rich descriptions
- Wellness and self-discovery platforms: combine angel numbers with numerology, tarot, and astrology for comprehensive spiritual profile building and holistic guidance experiences

## Endpoints

- `GET /api/v2/angel-numbers/numbers` List All Angel Numbers
- `GET /api/v2/angel-numbers/numbers/{number}` Get Angel Number Meaning
- `GET /api/v2/angel-numbers/lookup` Analyze Any Number Sequence
- `POST /api/v2/angel-numbers/daily` Daily Angel Number

### Angel Numbers (`/angel-numbers/`)
- `GET /angel-numbers/numbers/{number}` — Canonical number meaning (string param, e.g. `1111`, `777`).
- `GET /angel-numbers/lookup?number=` — Universal lookup for any positive integer with digit-root fallback.
- `POST /angel-numbers/daily` — Daily-message endpoint.

## Example Response

```
GET /api/v2/angel-numbers/numbers/444
```

```json
{
  "number": "444",
  "title": "Angelic protection, solid foundations, and encouragement to keep going",
  "coreMessage": "You are protected and supported by your angels. Keep building on solid foundations. Your hard work will pay off.",
  "type": "repeating",
  "digitRoot": 3,
  "meaning": {
    "spiritual": "Angel Number 444 is one of the most reassuring numbers you can receive from the angelic realm. It's a clear sign that you are surrounded by angels who are protecting and guiding you. You are not alone on your journey. The number 4 represents stability, structure, hard work, and solid foundations. When quadrupled as 444, it emphasizes the importance of building your life on a strong base of integrity, discipline, and dedication. Your angels are acknowledging the hard work you've been putting in. They see your efforts, even when others don't. 444 is their way of saying \"keep going—you're on the right track.\"",
    "love": "In love, 444 emphasizes the importance of building a relationship on solid foundations. Trust, honesty, loyalty, and commitment are the cornerstones of lasting love. Ensure these elements are present in your partnership. For singles, 444 suggests working on yourself before seeking a relationship. Build your own life—your career, your health, your friendships—and a partner who complements your solid foundation will appear. If you're facing relationship challenges, 444 reminds you to work through them rather than avoid them. Addressing issues head-on builds a stronger bond in the long run.",
    "career": "Professionally, 444 is a sign that your hard work is about to pay off. The foundations you've been building will soon support significant success. Keep showing up, keep doing the work, and trust that rewards are coming. This number also emphasizes the importance of integrity in your career. Build your professional reputation on honesty and reliability. These qualities will serve you better than any shortcuts. Financially, 444 encourages practical money management. Create budgets, pay off debts, and build savings. The security you create now will support future abundance.",
    "twinFlame": "For twin flames, 444 indicates that angels are supporting your connection. Even if you're in separation, know that divine beings are working to bring you together when the time is right. This number also suggests that both twin flames need to work on building solid foundations in their individual lives. Union requires two whole people coming together, not two halves seeking completion. If you're in twin flame union, 444 encourages you to build practical aspects of your life together—home, finances, shared goals. Your spiritual connection needs earthly foundations to thrive."
  },
  "keywords": [
    "protection",
    "foundation",
    "angelic support",
    "stability",
    "angel number",
    "synchronicity"
  ],
  "energy": "positive",
  "affirmation": "I am surrounded by angelic protection and my hard work is recognized.",
  "actionSteps": [
    "Trust that you are protected and guided by your angels at all times",
    "Continue your hard work—recognition and reward are coming",
    "Build solid foundations in all areas of your life",
    "Stay disciplined and committed to your goals",
    "Act with integrity in all your dealings"
  ]
}
```

## SDK Quick Start

```typescript
// npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } });
```

```python
# pip install roxy-sdk
import os
from roxy_sdk import create_roxy
roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"])
result = roxy.angel_numbers.analyze_number_sequence(number='1111')
```

```php
// composer require roxyapi/sdk (PHP 8.2+, built on Saloon)
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->angelNumbers->analyzeNumberSequence(number: '1111');
```

Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`).

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/angel-numbers`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
GET  /angel-numbers/numbers                   -> get_angel_numbers_numbers
GET  /angel-numbers/numbers/{number}          -> get_angel_numbers_numbers_number
GET  /angel-numbers/lookup                    -> get_angel_numbers_lookup
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Field Formats (agent gotchas)

Fields LLMs most often get wrong. Copy the format exactly.

| Field | Format | Good | Bad |
|-------|--------|------|-----|
| `number` (angel number path) | String | `"1111"`, `"777"` | `1111` (integer fails path validation) |

**Path hygiene:** no trailing slashes on any endpoint.

## Common Mistakes (verified from production)

LLMs frequently produce broken Angel Numbers code. These are the correct patterns.

- By-number path param is a STRING: `GET /angel-numbers/numbers/1111`. If you pass integer `1111` to a typed client it may fail.
- `/lookup` works for any positive integer, not just canonical angel numbers. It uses digit-root fallback — never generate "only 111/222/333/etc are valid" validation logic.

## Domain Gotchas

LLMs hallucinate confidently in this category. These are the specific traps.

- **Angel number lookup works for any positive integer.** Digit-root fallback covers non-canonical numbers. Do not generate validation logic that rejects non-`111`/`222`/`333` patterns.

## Multi-language Support

Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text.

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Related Surfaces

- **Guide:** [Angel Numbers integration guide](https://roxyapi.com/docs/guides/angel-numbers.md)
- **Starter app:** [AI Astrology Chatbot](https://github.com/RoxyAPI/astrology-ai-chatbot) — clone, add an API key, deploy.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/angel-numbers/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.