Using OpenAI in Bubble.io: The API Connector Setup Guide
The definitive reference for configuring OpenAI in Bubble.io’s API Connector — covering every endpoint, authentication pattern, parameter option, and common pitfall developers encounter.
Setting Up OpenAI Authentication in Bubble
All OpenAI API calls require a Bearer token. Here is the exact configuration.
In Plugins → API Connector → Add another API:
- API Name: OpenAI
- Authentication: Private key in header
- Key name: Authorization
- Key value: Bearer sk-YOURKEY (mark as Private)
Add a shared header for all calls:
Content-Type: application/json📌 Marking the Authorization header as ‘Private’ in Bubble ensures the API key is never exposed in the browser. All calls are proxied through Bubble’s server.
The Five OpenAI Endpoints You Will Actually Use
Each endpoint serves a different purpose. Configure each as a separate call within the same OpenAI API.
| Endpoint | Method | Use Case |
|---|---|---|
| /v1/chat/completions | POST | Text generation, chatbots, summarisation, classification, Q&A |
| /v1/embeddings | POST | Semantic search, similarity matching, recommendation engines |
| /v1/images/generations | POST | AI image generation from text prompts (DALL·E 3) |
| /v1/audio/transcriptions | POST | Convert uploaded audio to text (Whisper) |
| /v1/moderations | POST | Check user-generated content for policy violations |
Full Parameter Reference
Every parameter available in the chat completions endpoint and when to use each.
Required Parameters
- model — Which model to use. Start with gpt-4o-mini for cost efficiency.
- messages — Array of message objects with role and content fields.
Optional but Important
- max_tokens — Cap on response length. Set this always to control costs.
- temperature — Randomness (0-2). 0 = deterministic, 1 = balanced, 2 = very creative.
- response_format — Set to {“type”:”json_object”} for structured JSON output.
- stream — Set true for streaming responses (requires special Bubble handling).
For structured output (making the AI return valid JSON), use this body pattern:
{
"model": "gpt-4o-mini",
"response_format": { "type": "json_object" },
"messages": [
{
"role": "system",
"content": "You respond only in valid JSON with this structure: {'category': string, 'confidence': number}"
},
{ "role": "user", "content": "" }
]
} Setting Up Semantic Search in Bubble
Embeddings let you find the most relevant database records for any user query — far more powerful than keyword search.
Generate embeddings for your content
For each record in your database (articles, products, FAQs), call /v1/embeddings with the text content and model text-embedding-3-small. Store the returned embedding (a large array of floats) in a long text field.
Generate an embedding for the user query
When a user searches, call the same embeddings endpoint with their search query. You now have a numeric vector representing their intent.
Calculate cosine similarity in a backend workflow
Loop through your database records, calculate cosine similarity between the query embedding and each record’s stored embedding, and return the top N results sorted by similarity score.
Display relevant results
Populate a Repeating Group with the top matched records. Users see semantically relevant results even when they use different words than your content does.
Errors You Will Encounter and How to Fix Them
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | API key missing or incorrect | Verify the Authorization header value starts with ‘Bearer sk-‘ |
| 429 Rate Limit | Too many requests per minute | Add exponential backoff retry logic in your workflows |
| 400 Bad Request | Malformed JSON in request body | Check that all dynamic parameters are populated before the API call |
| Context length exceeded | Conversation history too long | Trim the messages array to the last N turns before sending |
| Empty response | max_tokens too low | Increase max_tokens; the model cut off mid-response |
Need Help With Your OpenAI + Bubble.io Integration?
SA Solutions specialises in production-grade Bubble.io AI integrations. We have solved every error above (and more) across dozens of client applications.
