RoxyAPI
Quick StartAGENTS.mdSDKMCP SetupFree StartersAPI Playground
  1. Docs
  3. Integrations
  5. FlutterFlow

Use RoxyAPI with FlutterFlow

Build a natal chart screen, a daily horoscope card, a tarot reading flow, or a Vedic kundli generator inside any FlutterFlow app in under 20 minutes. iOS, Android, and Web from one project, no Dart required.

FlutterFlow is the visual builder for native Flutter apps. It ships a built-in HTTP client called API Calls that handles headers, query strings, JSON bodies, and dynamic variables, plus a one-click Swagger/OpenAPI importer that loads every Roxy endpoint into your project at once. Every field of every Roxy response can be turned into a typed Custom Data Type that you drag onto any widget on any screen.

What you can build on FlutterFlow

  • Daily horoscope screen with a sign picker, bound to a Backend Query that fires on page load
  • Birth chart generator that accepts date, time, and place from a form, saved to Firestore or Supabase
  • Tarot reading flow with three card and Celtic Cross spreads rendered in a ListView
  • Life Path calculator that captures name and birth date, persisted to user profile
  • Vedic kundli screen with nakshatra, dasha periods, and panchang in collapsible cards
  • Dream meaning lookup screen on a search input
  • AI astrology chatbot built on FlutterFlow AI Agents with Roxy endpoints registered as tools

What you need, 30 seconds

  1. A Roxy API key. Get one on the pricing page.
  2. A FlutterFlow project. The free plan caps you at 2 API endpoints, so any plan above the free tier is recommended for the full Roxy surface. Check the FlutterFlow pricing page before you upgrade.
  3. Five minutes.

Run the quickstart curl once in a terminal before you wire the key into FlutterFlow. A successful JSON response confirms the key is good in isolation, before any builder UI is in the picture.

Step 1, connect your endpoints

There are two paths in FlutterFlow. Bulk import loads every Roxy endpoint at once from our OpenAPI spec. Manual adds one endpoint at a time. Bulk import is the right default. Manual is fine if you only need two or three endpoints.

This loads all 130+ Roxy endpoints into your project as a single grouped collection.

  1. Save the Roxy OpenAPI spec to your computer. In a terminal:
    curl -o roxyapi.json https://roxyapi.com/api/v2/openapi.json
    Or open the URL in a browser and pick File, Save As with the filename roxyapi.json.
  2. In FlutterFlow, open API Calls from the left navigation.
  3. Click the Import OpenAPI icon (top of the API Calls panel).
  4. Click Upload File, select roxyapi.json, then Import.

FlutterFlow creates one API Group named after the spec, with every Roxy endpoint inside, and pre-fills method, URL, headers, query parameters, and request body shapes.

Now add the auth header at the group level so it propagates to every call:

  1. Open the imported API Group.
  2. Go to the Headers tab and click + Add Header.
  3. Name X-API-Key. Value: paste your key from your account. Save.

Every endpoint inside the group inherits that header. One header, full surface.

Brackets, not braces. FlutterFlow URL variables use [name] syntax. Our API reference shows paths in OpenAPI {name} form. The bulk import handles the conversion for you. If you copy a path manually, swap {sign} for [sign] before saving the call.

Step 2, ship a useful feature

Here is the full flow for a daily horoscope screen. One sign picker, one text card, one auto-fired Backend Query.

  1. Drop a DropDown widget on the page. Options: the 12 zodiac signs (aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces).
  2. Bind the dropdown value to a Page State variable named selectedSign, default aries.
  3. Drop a Column below the dropdown. Inside the column add three Text widgets, one for the overview, one for lucky number, one for energy rating.
  4. Select the page itself in the widget tree. Open the Backend Query panel and click + Add Backend Query.
  5. Query Type API Call. Group or Call Name getDailyHoroscope.
  6. Map the sign variable to the Page State selectedSign.
  7. Bind each result Text widget to a field on the response: overview, luckyNumber, energyRating.

Run the project. Pick a sign. The screen rerenders with the horoscope for that day automatically.

For a POST endpoint like natal chart, the FlutterFlow side is a Form, an API Call action wired to the On Submit trigger of a button, and an Action Output Variable Name (for example chartResult) that downstream actions read from.

The body for POST /astrology/natal-chart is a JSON object with five fields. FlutterFlow renders this as a Variables tab on the API call, where each variable can be bound to a TextField, DatePicker, or Page State value:

VariableTypeSource on the form
dateString, format YYYY-MM-DDDatePicker formatted output
timeString, format HH:MM:SSTimePicker plus :00 suffix
latitudeDoubleNumber TextField
longitudeDoubleNumber TextField
timezoneString, IANA zonePlain TextField, default America/New_York

City to coordinates is painful for end users. Roxy includes a location endpoint at GET /location/search?q=mumbai that returns latitude, longitude, and an IANA timezone string. Wire it to a search-as-you-type field, fire it on debounce, and let the user pick a city. Three input fields collapse into one.

Custom Data Types from JSON

FlutterFlow can convert any JSON response into a typed Custom Data Type. This is the cleanest way to bind nested fields like planets, houses, or nakshatras to ListView and ListTile widgets without writing JSON path expressions everywhere.

  1. Open the API call. Switch to the Response & Test tab.
  2. Fill in test variables and click Test API Call to fetch a real response.
  3. Click Generate Data Type above the response viewer.
  4. FlutterFlow infers field names and types, creates a Custom Data Type, and offers to set it as the call response type.

Now any widget that reads from the call result has a typed dropdown of fields. ListView builders bind to chart.planets, ListTile titles bind to planet.name and planet.sign. Drag and drop, no manual JSON path syntax.

OAS 3.0 is the supported import format and our spec is OAS 3. If you ever import an external OAS 2.0 spec, FlutterFlow may drop body fields silently. Stick with OAS 3 sources.

Step 3, scale to the full surface

If you bulk imported, every endpoint is already in your project. Three places to figure out which one to call next:

Caching API responses

FlutterFlow does not cache HTTP responses by default. Two options for daily content:

  1. App State variable, persisted, with a lastFetched timestamp. Read state, if it is the same calendar day return the cached payload, otherwise fire the API call and update.
  2. Firestore or Supabase document keyed by date and sign. A scheduled Cloud Function refreshes the document once per day. The app reads from the document, never from Roxy.

The Firestore or Supabase pattern is best for high-traffic apps because it shifts every cached read off your Roxy quota.

Keeping the key out of the app bundle

FlutterFlow apps compile to native iOS, Android, and Web bundles. Anything stored as a static value in API Calls, Constants, or App State ends up inside the compiled app where a determined user can extract it. Three approaches by security level, weakest to strongest:

ApproachHowWhen it is fine
Static header value on the API GroupPaste the key directly into the X-API-Key header valueInternal tools, prototypes, demos behind auth
FlutterFlow private API callAPI Call, Advanced Settings, toggle Make Private on. Routes the call via Firebase Cloud Functions, the key stays on the server.Public Firebase-backed apps
Your own backend proxyStand up a small Cloudflare Worker or Vercel Route Handler that holds the key, exposes a thin pass-through, and rate-limits per user. Point FlutterFlow at the proxy URL.Public Supabase-backed apps, or any app where you need per-user metering. The Next.js integration covers the pattern.

Make Private requires Firebase. The toggle proxies the call through Firebase Cloud Functions, which means your FlutterFlow project needs Firebase enabled and a Firebase Blaze plan (Cloud Functions are not on the free Spark plan). For Supabase-only or backend-less projects, the FlutterFlow private call path is not available, and you should use the proxy pattern instead.

Gotchas

  • Brackets versus braces. FlutterFlow path variables use [sign], not the OpenAPI {sign} form you see in our reference. The bulk OpenAPI import converts these for you. Manual entry needs the swap.
  • Free plan caps API endpoints at 2. Bulk-importing Roxy creates 130+ endpoints, so the free FlutterFlow plan will reject the import. Any plan above the free tier removes the cap.
  • OpenAPI re-import overwrites references. If you re-upload the spec after wiring widgets to a call, FlutterFlow may regenerate the call IDs and break the bindings. Import once and add new endpoints manually thereafter, or follow the Update existing option if FlutterFlow shows it.
  • Library Publishing is the Marketplace path. FlutterFlow Libraries (the Marketplace dependency system) require a paid plan with branching. The OpenAPI import covers the same ground for now without any Library setup.
  • Timezone. Prefer IANA strings ("America/New_York", "Asia/Kolkata") over decimal offsets. The server resolves IANA to the DST-correct offset for the request date. Decimal offsets like 5.5 are accepted but do not handle daylight saving.
  • Rate limits. Every Roxy plan has daily and monthly caps. Cache daily content as App State or in Firestore rather than calling on every page load.
  • Header private flag. If you mark an individual API call as private, FlutterFlow does not auto-inherit the group level X-API-Key header. Re-add the header on the private call itself, or move the key to a Firebase environment variable inside the generated Cloud Function.
  • Hot reload after a header change. Changes to API Group headers require a project hot reload to apply in Run mode. If a call returns 401 right after you save a new key, restart the runner.

What to build next