# Use RoxyAPI with Bubble

> Add a natal chart generator, a daily horoscope page, a Life Path calculator, or a tarot reading widget to your [Bubble](https://bubble.io/) app in under 20 minutes. No code required.

Bubble is the most-used full-stack no-code builder on the web. Its API Connector plugin routes every RoxyAPI call through a Bubble server so the key stays out of visitor browsers. The pattern below covers the exact clicks for auth, calls, and data binding.

## What you can build on Bubble

- Daily horoscope pages bound to a sign dropdown with dynamic text elements
- Birth chart generator that saves kundli data to the Bubble database
- Tarot reading app with three-card or Celtic Cross spreads rendered in a repeating group
- Life Path calculator that captures name and birth date on a form
- Vedic kundli page with nakshatra, dasha, and panchang pulled into a Thing
- Dream interpretation lookup on a search input
- Daily crystal recommendation bound to a user profile page

## What you need, 30 seconds

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. A Bubble app. The free tier works for development. A paid Bubble plan is needed to deploy publicly.
3. The API Connector plugin. Free, Bubble-built, and installed from the plugin gallery.

**Tip: If you have not hit RoxyAPI from anywhere yet, run the [quickstart](/docs/quickstart) curl once in a terminal. A successful JSON response confirms the key is good before you paste it into Bubble.**

## Step 1, connect your first endpoint

The one rule: your Roxy key goes in the auth dropdown at the API level. Not in an Option Set. Not in a custom state. Not in a workflow. The auth dropdown is the only place Bubble keeps it out of the browser bundle.

1. **Plugins** in the left sidebar, then **Add plugin**.
2. Search `API Connector`, install the official Bubble-made plugin.
3. Open the API Connector, click **Add another API**.
4. **API name** `RoxyAPI`.
5. **Authentication** `Private key in header`.
6. **Key name** `X-API-Key` (hyphens required).
7. **Key value** paste your key from [your account](/account).

Every call you add under this API inherits the header. You set auth once, every endpoint is unlocked.

**Warning: Never put the key in any other Bubble field. Page elements, Option Sets, custom states, the database, and workflow inputs are all readable from the browser or from database exports. The auth dropdown is the only safe home.**

Add your first call:

1. Click **Add another call**.
2. **Call name** `GetDailyHoroscope`.
3. **Use as** pick **Data** (for page bindings) or **Action** (for workflows). See the table below.
4. **Method** `GET`.
5. **URL** paste:
   ```
   https://roxyapi.com/api/v2/astrology/horoscope/[sign]/daily
   ```
6. The `[sign]` placeholder creates a parameter row. Set **Default value** `aries`, leave **Private** unchecked on the sign param (zodiac signs are not secrets).
7. Click **Initialize call**. Bubble fires the request, learns the response shape, and exposes every field as a dynamic property.

| Use as | Where it appears | Best for |
|--------|------------------|----------|
| **Data** | Under "Get data from external API" on any element | Daily horoscope panels, dream lookups, tarot card displays |
| **Action** | In the workflow editor under Plugins, RoxyAPI | Form submits, "generate my chart" buttons, database writes |

## Step 2, ship a useful feature

Here is the full flow for a daily horoscope page. One dropdown, one text element, one API call.

1. Drop a **Dropdown** on the page. Options: the 12 zodiac signs.
2. Drop a **Text** element.
3. Click the text, **Insert dynamic data**, **Get data from external API**.
4. Pick **RoxyAPI, GetDailyHoroscope**.
5. In the parameter dialog, drag the dropdown value into the `sign` parameter.
6. Pick the response field you want: `overview`, `luckyNumber`, `moonSign`, `energyRating`, and so on.

Preview the page, pick a sign, see the horoscope for today render instantly.

For a POST endpoint like natal chart:


### API Connector body

1. **Add another call**, **Method** `POST`.
2. **URL** `https://roxyapi.com/api/v2/astrology/natal-chart`.
3. Under **Shared headers** add `Content-Type: application/json`.
4. **Body type** `JSON`, paste:
   ```json
   {
     "date": "<date>",
     "time": "<time>",
     "latitude": <latitude>,
     "longitude": <longitude>,
     "timezone": "<timezone>"
   }
   ```
5. Set parameter types: `date` text (`YYYY-MM-DD`), `time` text (`HH:MM:SS`), `latitude` number, `longitude` number, `timezone` text (IANA string like `"America/New_York"`).
6. Initialize with test data.

### curl preview

```bash
curl -X POST "https://roxyapi.com/api/v2/astrology/natal-chart" \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-12",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timezone": "America/New_York"
  }'
```


Hook the action to a form submit, then save the response as a new `Chart` Thing. Dynamic binding in Bubble renders every planet, house, and aspect directly from the database record.

## Step 3, scale to the full surface

Every new endpoint is another call under the same `RoxyAPI` API. The auth header is reused automatically. Three places to pick the next one:

- **[API reference](/api-reference)** has a cURL import feature. Paste any curl example from the reference and Bubble fills in method, URL, headers, and body for you.
- **Domain guides** for which endpoints to call in what order:
  - [Western Astrology](/docs/guides/astrology), [Vedic Astrology](/docs/guides/vedic-astrology), [Tarot](/docs/guides/tarot), [Numerology](/docs/guides/numerology), [I Ching](/docs/guides/iching), [Dreams](/docs/guides/dreams), [Crystals](/docs/guides/crystals), [Angel Numbers](/docs/guides/angel-numbers)
- **Most-used endpoints** that fit Bubble well: [`GET /astrology/horoscope/{sign}/daily`](/api-reference#tag/western-astrology/GET/astrology/horoscope/{sign}/daily), [`POST /astrology/natal-chart`](/api-reference#tag/western-astrology/POST/astrology/natal-chart), [`POST /vedic-astrology/birth-chart`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/birth-chart), [`POST /tarot/spreads/three-card`](/api-reference#tag/tarot/POST/tarot/spreads/three-card), [`POST /numerology/life-path`](/api-reference#tag/numerology/POST/numerology/life-path), [`POST /numerology/chart`](/api-reference#tag/numerology/POST/numerology/chart), [`GET /dreams/symbols`](/api-reference#tag/dreams/GET/dreams/symbols).

## Caching responses in the Bubble database

Bubble does not cache API Connector responses. For daily content, save the response to a Thing keyed by date and sign, and have your pages read from the database. Run a scheduled Backend Workflow once per day per sign to refresh the Things.

1. Create a `DailyHoroscope` data type with fields `sign`, `date`, `overview`, `luckyNumber`, and so on.
2. Schedule a daily API workflow that loops through 12 signs and writes one Thing per sign.
3. Page elements read the Thing for today and the picked sign.

This pattern keeps your Roxy quota flat regardless of traffic.

## Gotchas

- **Backend-only key.** Always use the **Private key in header** auth dropdown. Never put the key in any Bubble page element, Option Set, workflow input, custom state, or database field. Those end up in the browser bundle or in a database export.
- **Never tick "Allow call to run directly in the browser".** This option only appears for public calls, but switching to it leaks the key if one exists. Leave it off.
- **Timezone.** Prefer IANA strings (`"America/New_York"`) over decimal offsets. The server resolves IANA to the DST-correct offset for the request date. Decimal offsets like `-5` are accepted but do not handle daylight saving.
- **Rate limits.** Each Roxy plan has daily and monthly caps. Cache daily content in a `DailyHoroscope` Thing rather than calling the API on every page load.
- **Initialize after every schema change.** Bubble caches the response shape from the last successful Initialize. If you change URL, params, or body, hit Initialize again or the new fields will not appear in the dynamic data picker.
- **Use as Data vs Action.** Data binds to page elements. Action fires in workflows. You can add the same endpoint twice with different names if you need both.

## What to build next

- Browse the [Astrology](/docs/guides/astrology) and [Vedic Astrology](/docs/guides/vedic-astrology) guides for endpoint ordering.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) covers multi-domain conversational patterns you can wire into a Bubble workflow.
- The [API reference](/api-reference) is the source of truth for every field on every response.
- The [SDK guide](/docs/sdk) is there when you outgrow no-code and want typed calls.