Bubble

Add RoxyAPI to your Bubble app and ship a natal chart generator, daily horoscope page, Life Path calculator, tarot reading widget, or full Vedic kundli explainer without writing a single line of JavaScript. One API key, 10 domains, 130+ endpoints, all wired up through the official API Connector plugin. If you are a Bubble vibe coder building an astrology, tarot, numerology, dream, or spiritual app, this is the page you need.

Bubble is the most popular full-stack no-code platform for building production web apps. It has its own database, workflow engine, and visual page builder. The API Connector plugin lets Bubble talk to any REST API, including RoxyAPI, with the calls running through Bubble's server so your API key stays safe.

Before you start

• A RoxyAPI account and an API key. Grab one from the pricing page, or test endpoints first with the pre-filled key on the interactive API reference.
• A Bubble app. The free tier works for development, but you need a paid Bubble plan to deploy publicly. Bubble's API Connector itself is free.
• Ten minutes.

The one rule: always mark your API key as Private

This is the single most important rule on this page. Everything else is a corollary.

Bubble's API Connector has two ways to attach values to a call: Private and client-safe (the Private checkbox unchecked). A Private value never reaches the user's browser. A client-safe value gets baked into your app's source code where any visitor can read it with browser DevTools. Your RoxyAPI key must always be Private. Always. There is no situation where exposing it is acceptable.

Bubble's own docs put it bluntly: "API keys/tokens should never be stored in Option Sets or in on-page elements and/or workflows, since that makes them visible in your application's client-side source code."

The good news: the API Connector's default for header values is to require you to think about it. The bad news: if you tick the Private box wrong even once on a header, your key is leaked. We will walk through the exact clicks below so this never happens.

Step 1: install the API Connector plugin

The API Connector is a Bubble-built plugin you install once per app.

1. In the Bubble editor, click Plugins in the left sidebar
2. Click Add plugin
3. Search for API Connector
4. Click Install on the official Bubble-made API Connector (verified badge)
5. Close the plugin gallery

The plugin now appears in your Plugins list. Click it to open the configuration panel.

Step 2: add a new API and pick the right authentication

1. In the API Connector configuration panel, click Add another API
2. Set the API name to RoxyAPI (this name is used to organise your calls; it shows up in workflow editors as RoxyAPI - GetDailyHoroscope)
3. Set Authentication to Private key in header

Step 3: configure the shared header

When you select "Private key in header", Bubble shows two fields right below the auth dropdown:

1. Key name: enter X-API-Key exactly (hyphens required, case does not matter, spelling does)
2. Key value: paste your RoxyAPI key from your account page

That is it. Every call you add to this API will automatically include the X-API-Key header on every request. You do not need to add it again per call.

Step 4: add your first call

Now we add the actual API endpoint. Let us start with a daily horoscope.

1. In the same RoxyAPI panel, click Add another call
2. Call name: GetDailyHoroscope
3. Use as: pick Data (we are fetching data to display, not triggering a workflow action — see the "Data vs Action" section below for when to use which)
4. Data type: leave as JSON (RoxyAPI always returns JSON)
5. Method: GET
6. URL: paste this exactly:

   https://roxyapi.com/api/v2/astrology/horoscope/[sign]/daily

7. The square brackets around sign tell Bubble that sign is a parameter to fill in at runtime. Bubble automatically detects it and adds a parameter row underneath the URL field.
8. In the parameter row that just appeared, set the Default value to aries (this is just for testing — it gets replaced with the user's chosen sign in your app)
9. Make sure the Private checkbox is unchecked for the sign parameter (the zodiac sign is not a secret, so the user is allowed to set it)

Step 5: initialize the call

Bubble does not let you use a call in your app until you have run it once successfully. This is called "initializing" — Bubble fires the request, looks at the response, and learns the JSON structure so the editor can show you every field as a draggable property.

1. Click the Initialize call button at the bottom of the call config
2. Wait a second or two
3. A popup shows the response

A healthy RoxyAPI response looks like this:

{
  "sign": "Aries",
  "date": "2026-04-13",
  "overview": "Today, your natural leadership shines through...",
  "love": "Venus in your 5th house favours playful encounters...",
  "career": "Mars supports decisive action on a stalled project...",
  "luckyNumber": 7,
  "luckyColor": "Red",
  "moonSign": "Libra",
  "energyRating": 8
}

4. Click Save

The call is now live. Every field above (overview, luckyNumber, moonSign, etc.) is now a draggable property in the Bubble editor under any text element's dynamic data picker.

Display the horoscope on a page

1. Open any page in your Bubble app
2. Drop a Text element on the page
3. Click into the text field, click Insert dynamic data
4. Choose Get data from external API
5. Choose RoxyAPI - GetDailyHoroscope
6. In the parameter dialog, drag the user's selected sign (from a dropdown, an input, or wherever you capture it) into the sign parameter
7. After the call, choose the field you want: overview, love, career, luckyNumber, etc.

That is the whole flow: install plugin, add API, add call, initialize, drop on page. No code.

"Use as Data" vs "Use as Action"

Bubble asks this question for every call. The choice changes where it shows up in your app.

A lot of RoxyAPI use cases need both. For a natal chart app you typically want:

• One call set to Data for "show today's transits at the top of every page"
• One call set to Action for "user submits the birth form, generate their chart, save the result to a Bubble Thing in the database"

You can add the same endpoint twice with different "Use as" settings. Just give them different names like GetNatalChart_Data and GenerateNatalChart_Action.

Send a JSON body for POST endpoints

Endpoints like /astrology/natal-chart, /astrology/synastry, /vedic-astrology/birth-chart, and /numerology/life-path take a JSON body. Here is how to send one in Bubble.

1. Add a new call (Step 4 above)
2. Set Method to POST
3. Set URL to the endpoint, for example https://roxyapi.com/api/v2/astrology/natal-chart
4. Find the Body type dropdown and pick JSON
5. In the Body text area, paste your JSON with parameter placeholders in square brackets:

{
  "datetime": "<datetime>",
  "latitude": <latitude>,
  "longitude": <longitude>,
  "timezone": "<timezone>"
}

6. Bubble detects the angle-bracket placeholders (or square brackets, depending on your Bubble version) and creates parameter rows for each one
7. For each parameter, set a Default value for testing, leave Private unchecked (these are user inputs, not secrets), and pick the right Type (text, number, etc.)
8. Add this header to make the call body parse correctly: under Shared headers for this API (or under Headers for this individual call), add Content-Type: application/json
9. Initialize the call to test
10. Save

Once initialized, you can call this from a workflow action. Drag user input fields into each parameter when you wire it up.

Critical security rules

These are the four rules that keep your RoxyAPI key out of attackers' hands. If you break any of them, your key is leaked and your quota is gone.

1. Never put your API key anywhere except the auth dropdown's Key value field. Not in Option Sets. Not in page elements. Not in custom states. Not in workflows. Not in the database. The auth dropdown is the only safe place.
2. Never tick the "Private" checkbox off on a header that contains a secret. The auth dropdown handles this for you, but if you ever add headers manually to a call, double-check the Private box is ticked on any sensitive ones.
3. Set Use as: Data only for calls that do not depend on user-specific secrets passed as query strings or body params. Bubble's docs warn explicitly that some "Use as: Data" configurations skip privacy rules. Stick to the Private key in header auth method and you are fine.
4. Never enable "Allow call to run directly in the browser where applicable". This option only appears for public calls (Authentication: None, no headers, no private parameters), but if you ever switch your auth to None and tick this box, you bypass Bubble's server entirely and your key (if you somehow added one) ends up in the browser. Just leave it unchecked.

Test your API key outside Bubble first

Before you wire anything into the API Connector, confirm your key works on its own. Open a terminal and run:

curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: YOUR_KEY"

If that prints JSON, the key is good and any error you see in Bubble is a configuration issue, not a RoxyAPI issue. If it returns 401, the key is wrong or your subscription is inactive. Check at your account page.

Troubleshooting

"Initialize call" returns 401 api_key_required

{
  "error": "API key is required. Provide via X-API-Key header or api_key query param",
  "code": "api_key_required"
}

The header did not reach the server. Check the API-level config (not the call-level):

1. Authentication dropdown is set to Private key in header (not None, not HTTP Basic Auth)
2. Key name is spelled exactly X-API-Key (hyphens required)
3. Key value has your full key with no leading or trailing whitespace, no quotes

401 invalid_api_key

The header is present but the key value is wrong. Re-paste the key from your account, strip whitespace, and try again.

429 rate_limited

You hit your monthly plan quota. Every RoxyAPI response carries X-RateLimit-Remaining and X-RateLimit-Reset headers. Reduce how often your app calls the same endpoint (cache results in the Bubble database for 24 hours for daily content), or upgrade on the pricing page.

404 not_found with a suggestion field

{
  "error": "Not found",
  "code": "not_found",
  "suggestion": "Did you mean POST /astrology/natal-chart?",
  "docs": "https://roxyapi.com/products/astrology-api"
}

The URL is wrong. RoxyAPI returns the closest valid route in the suggestion field. Copy that path into the URL field of your call and re-initialize.

405 method_not_allowed

You used the wrong HTTP verb. The response allow array lists valid methods. Change the Method dropdown for your call and re-initialize.

Initialize succeeds but my page does not show any data

You forgot to re-initialize after editing the call. Bubble caches the response schema from the last successful Initialize, so any changes you make after the fact (URL change, parameter added, body field added) require another Initialize click. If the schema is stale, the field you want will not appear in the dynamic data picker.

"Get data from external API" does not show my call

Either you forgot to initialize the call (it must succeed once before it appears), or the call is set to Use as: Action instead of Use as: Data. Action calls only show up in the workflow editor.

Sensitive data leaked in app source code

You ticked the Private checkbox off on a header or parameter that contains a secret. Open the call, find the offending field, tick the Private box back on, re-initialize, and rotate your RoxyAPI key on your account page since the old one is now compromised.

Extend your integration

You have one endpoint working in Bubble. Adding the next 130 is the same pattern: click Add another call in your RoxyAPI API panel, change the URL, change the body, the Private key in header auth is reused on every call. Three places to find the next endpoint to wire up:

• Interactive API reference — Scalar-powered live docs for every endpoint across all 10 domains. Try a call in the browser with the pre-filled test key, copy the curl example, then paste it into the API Connector's Import cURL feature and Bubble fills in the URL, method, and body for you.
• Domain guides — short walkthroughs of which endpoints to call in what order for a given product:
  • Western Astrology guide — natal charts, horoscopes, synastry, transits
  • Vedic Astrology guide — kundli, Gun Milan, Vimshottari Dasha, panchang, KP
  • Tarot guide — daily card, three-card, Celtic Cross, custom spreads
  • Numerology guide — Life Path, Expression, Soul Urge, personal year
• One API, many calls. Every call you add under the same RoxyAPI API entry inherits the same Private key in header credential. One auth setup at the API level, every call inherits it.

The pattern is the same every time: horoscope today, compatibility tomorrow, kundli next week. One auth setup, every endpoint unlocked.

What to build first

• Daily horoscope page per zodiac sign. Dropdown picker → text element bound to RoxyAPI GetDailyHoroscope → user picks a sign and sees the horoscope. The most common Bubble astrology app pattern, ships in 30 minutes.
• Birth chart generator with form. Form captures date, time, latitude, longitude, timezone → workflow action calls POST /astrology/natal-chart → save the result as a new "Chart" Thing in the Bubble database → display on a results page.
• Tarot reading app. Button → workflow action calls POST /tarot/spreads/three-card → save the three cards as a new "Reading" Thing → page renders the three cards in sequence with image elements.
• Life Path calculator. Form (name + birth date) → workflow action calls POST /numerology/life-path → display the number with its meaning. Optionally save to a "Profile" Thing for repeat lookups.
• Vedic kundli with nakshatra. Form (birth date, time, place) → workflow action calls POST /vedic-astrology/birth-chart → save kundli as a Thing → results page displays planets, nakshatra, Vimshottari Dasha, panchang from the database.
• Dream interpretation lookup. Search input → call GET /dreams/symbols set to Use as: Data → repeating group displays matching dream symbols.
• Daily crystal recommendation. Page-level data call to POST /crystals/daily → display today's crystal with image, properties, and zodiac compatibility.

FAQ

How do I connect Bubble to RoxyAPI?

Install the API Connector plugin, add a new API named RoxyAPI, set Authentication to Private key in header, set Key name to X-API-Key and Key value to your RoxyAPI key. Add a call (for example GetDailyHoroscope calling https://roxyapi.com/api/v2/astrology/horoscope/[sign]/daily), initialize it once, and then use it in any page or workflow.

Is the API Connector free on Bubble?

Yes. The API Connector is a Bubble-developed plugin available on every plan, including the free tier. There are no per-call fees from Bubble for using it. You only pay your RoxyAPI plan and your Bubble plan.

Will my API key leak to my Bubble app's users?

Not if you follow the steps on this page. Bubble's API Connector routes calls through Bubble's server by default, and the Private key in header auth method keeps the header value out of the client bundle. The dangerous configurations are: putting the key in an Option Set, putting it in a page element, marking a header parameter as not-Private, or enabling "Allow call to run directly from the browser". Avoid those four and your key stays safe.

Use as Data or Use as Action?

Use Data when the call returns information you want to render directly on a page (today's horoscope, a dream symbol lookup, a tarot card display). Use Action when the call is triggered by a button or form submission and you want to save the result to the Bubble database or do something else in a workflow. You can add the same endpoint twice as both Data and Action with different names if you need both.

How do I cache RoxyAPI responses to save quota?

Bubble does not have HTTP response caching on the API Connector itself. The right pattern: store the response in a Bubble Thing in the database with a date or hash key, and check for an existing Thing before calling RoxyAPI. For daily content like horoscopes, run a scheduled API workflow once per day per sign, save the result to a DailyHoroscope Thing, and have your pages read from the database instead of calling the API on every page load.

Can I run a scheduled workflow to fetch RoxyAPI data overnight?

Yes. Bubble's Backend Workflows let you schedule API calls. Create a backend workflow, add an action that calls your RoxyAPI Action call, and schedule it with the Schedule API workflow action. Use this for the caching pattern in the previous answer: schedule one workflow per zodiac sign that runs daily at midnight and saves the horoscope to the database.

How accurate are the astrology calculations under a Bubble app?

Every position comes from Roxy Ephemeris, verified against NASA JPL Horizons. See the methodology page for accuracy details. Same engine for every endpoint, regardless of which integration platform calls it.

Can I import a curl command into the API Connector?

Yes. The API Connector has a cURL import feature at the top of the call config. Paste any curl example from the API reference and Bubble parses the method, URL, headers, and body. This is the fastest way to set up a complex call without filling fields manually.

Where do I get a RoxyAPI key?

Visit the pricing page for paid plans, or try the interactive API reference with a pre-filled test key first. Plans start at 5,000 requests per month.

Is there a ready-made Bubble template for RoxyAPI?

Not yet. If you build a public Bubble template for astrology, tarot, numerology, or any other domain on RoxyAPI and want it featured on our starters page, reply to your onboarding email with the template URL. The first community Bubble template gets a free month on us.