# Use RoxyAPI with Dify

> Give a [Dify](https://dify.ai/) chatbot, agent, or workflow live access to astrology, tarot, numerology, I Ching, dreams, crystals, and angel numbers in under 20 minutes.

Dify is an open source LLM app platform. Drag nodes on a canvas, connect an LLM, and ship a working AI app without a backend. RoxyAPI slots in as either a single HTTP Request node or as a full Custom Tool with every endpoint auto-imported from our OpenAPI schema.

## What you can build on Dify

- AI astrology chatbot that routes birth-chart, daily horoscope, and synastry questions to the right endpoint
- Tarot reading agent that pulls three-card or Celtic Cross spreads and interprets them in your brand voice
- Life Path onboarding flow that greets users by their numerology profile
- Vedic kundli explainer agent that picks nakshatra, dasha, or panchang sub-endpoints on its own
- Dream interpretation bot that summarizes matching symbols from the dictionary
- Scheduled workflow that posts the daily crystal recommendation to Slack or Notion

## What you need, 30 seconds

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. A Dify workspace. Free at [cloud.dify.ai](https://cloud.dify.ai/), or run self-hosted. The integration is identical.
3. Five to ten minutes depending on path.

**Tip: If you are new to RoxyAPI, run the [quickstart](/docs/quickstart) curl in a terminal first. A successful JSON response confirms the key is good before you wire it into any Dify node.**

## Step 1, connect your first endpoint

Dify offers two paths. Pick based on scope. One endpoint, one node. Many endpoints in an agent, one Custom Tool.


### HTTP Request node

For one or two fixed endpoints (daily horoscope, Life Path lookup).

1. Open your app in **Studio**.
2. Click `+` between nodes, pick **HTTP Request**.
3. **Method** `GET` or `POST`.
4. **URL** paste the endpoint, for example `https://roxyapi.com/api/v2/astrology/horoscope/aries/daily`.
5. Scroll to **Authentication**, **API Key**, subtype **Custom** (not Basic, not Bearer).
6. **Header** `X-API-Key`, **Value** paste your key from [your account](/account).

That is the entire setup.

### Custom Tool from OpenAPI

For an agent that picks the right endpoint on its own. Every Roxy endpoint becomes a callable tool with parameter hints and type validation filled in from our schema.

1. **Tools** in the sidebar, **Custom Tools** tab, **Create Custom Tool**.
2. In the **Schema** field pick **Import from URL**, paste:
   ```
   https://roxyapi.com/api/v2/openapi.json
   ```
3. Click **Fetch**. Dify pulls every endpoint grouped by tag.
4. Scroll to **Authentication Method**, pick **API Key**, **Header name** `X-API-Key`, paste your key, **Save**.
5. Open or create an **Agent** app, scroll to **Tools**, **Add Tool**, pick the RoxyAPI tool.

Now ask the agent "what is my Life Path for 1990-05-12" or "give me a three-card tarot reading for career". The agent inspects the schema, picks the right endpoint, builds parameters, and calls Roxy behind the scenes.


**Warning: The single most common mistake is leaving the subtype on Bearer. RoxyAPI uses `X-API-Key` as a custom header, not `Authorization: Bearer`. If you see 401 `api_key_required`, check the subtype before anything else.**

For cleaner secrets handling, click **Environment Variables** in the left sidebar, add `ROXY_API_KEY`, and reference it as `{{ROXY_API_KEY}}` in the node value. Dify masks env vars in exports.

## Step 2, ship a useful feature

Here is the full flow for an AI tarot reader. Start captures a question, HTTP Request pulls a three-card spread, LLM interprets the three cards together rather than one at a time.

1. **Start** node, capture `question` as input.
2. **HTTP Request** node:
   - **Method** `POST`
   - **URL** `https://roxyapi.com/api/v2/tarot/spreads/three-card`
   - **Body** JSON with `{"question": "{{question}}"}`
   - Auth: **API Key, Custom, X-API-Key**
3. **LLM** node with a prompt like:
   > You are a thoughtful tarot reader. Three cards were drawn for the question: {{question}}. Past: {{api.positions[0].card.name}}. Present: {{api.positions[1].card.name}}. Future: {{api.positions[2].card.name}}. Weave them into a single reading in under 250 words.
4. **Answer** node returns the LLM output.

Variable substitution works everywhere in Dify. `{{sign}}` in a URL, `{{api_response.data.items[0].id}}` for deep object access, JSON body values like `{{birth_lat}}`.

For curl reference or an SDK equivalent outside Dify:


### curl

```bash
curl -X POST "https://roxyapi.com/api/v2/tarot/spreads/three-card" \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What should I focus on this quarter?"}'
```

### TypeScript SDK

```typescript
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data } = await roxy.tarot.castThreeCard({
  body: { question: 'What should I focus on this quarter?' },
});
```

### Python SDK

```python
import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ['ROXY_API_KEY'])
result = roxy.tarot.cast_three_card(question='What should I focus on this quarter?')
```

### PHP SDK

```php
<?php
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->tarot->castThreeCard(question: 'What should I focus on this quarter?');
```


## Step 3, scale to the full surface

For focused bots, import only the domain you need. Smaller tool surface means fewer wrong tool calls from the model.

| Domain | Schema URL | When to use |
|--------|------------|-------------|
| Western Astrology | `https://roxyapi.com/api/v2/astrology/openapi.json` | Natal charts, horoscopes, synastry, transits |
| Vedic Astrology | `https://roxyapi.com/api/v2/vedic-astrology/openapi.json` | Kundli, Guna Milan, Vimshottari Dasha, panchang, KP |
| Tarot | `https://roxyapi.com/api/v2/tarot/openapi.json` | Daily card, three-card, Celtic Cross, yes or no |
| Numerology | `https://roxyapi.com/api/v2/numerology/openapi.json` | Life Path, Expression, Soul Urge, personal year |
| I Ching | `https://roxyapi.com/api/v2/iching/openapi.json` | 64 hexagrams, changing lines, daily cast |
| Dreams | `https://roxyapi.com/api/v2/dreams/openapi.json` | Symbol dictionary, search, daily |
| Crystals | `https://roxyapi.com/api/v2/crystals/openapi.json` | By zodiac, by chakra, birthstones, search |
| Angel Numbers | `https://roxyapi.com/api/v2/angel-numbers/openapi.json` | By number, universal lookup, daily |
| Biorhythm | `https://roxyapi.com/api/v2/biorhythm/openapi.json` | Daily, forecast, critical days, compatibility |
| Location | `https://roxyapi.com/api/v2/location/openapi.json` | City search, timezone, coordinates |

Tour the [API reference](/api-reference) with the pre-filled test key to find the right endpoint, then paste the URL into an HTTP Request node or add the domain schema to a Custom Tool.

## Gotchas

- **Backend-only key.** Your Dify workspace runs server-side, so the API key lives safely in a node or env var. Never paste it into a chat prompt that gets logged or exported with the workflow.
- **Use Custom, not Bearer.** The `X-API-Key` header is a custom header. Leaving the Authentication subtype on Bearer is the single most common integration failure.
- **Timezone.** Prefer IANA strings like `"Asia/Kolkata"` or `"America/New_York"`. Decimal offsets like `5.5` are accepted but do not handle daylight saving. The server resolves IANA to the DST-correct offset for the request date.
- **Rate limits.** Every Roxy plan has daily and monthly caps. Agents that burn tools/call on every turn can eat a month of quota in hours. Add a decision node that only calls Roxy when the user question is on topic.
- **Tool surface discipline.** The full OpenAPI import gives your agent every endpoint. For smaller models (GPT-3.5, Mistral 7B), use per-domain schemas instead. Fewer tools means fewer wrong picks.
- **Per-request billing.** `tools/list` is free on our MCP endpoints, but every `tools/call` or HTTP request counts as a billable Roxy call.

## What to build next

- The [astrology guide](/docs/guides/astrology) and [Vedic astrology guide](/docs/guides/vedic-astrology) cover endpoint ordering for birth-chart agents.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows how to wire multiple domains into a conversational app.
- Our [MCP server](/docs/mcp) is the alternative to Custom Tools for clients that speak MCP natively (Claude Desktop, Cursor, Claude Code).
- Browse the [API reference](/api-reference) for every endpoint across 12 domains.