API Reference · v1

Fluxy API

The Fluxy API lets you integrate a Fluxy bot into any website, app, or backend you control. Create conversations, send messages, and read history — the exact same AI pipeline that powers Fluxy's own web widget and WhatsApp integration.

All requests are made server-to-server. Never call the Fluxy API directly from client-side code — your API secret would be exposed to anyone who opens their browser's network tab. Route requests through your own backend instead.

Authentication

Every request must include an API secret in the Authorization header, as a Bearer token. Each secret is scoped to a single bot — there's no need to also pass a bot ID or slug, the secret identifies it.

Generate a secret from your Fluxy dashboard: open a bot, go to its API tab, and click Generate secret. The plaintext value is shown exactly once — store it in your backend's environment variables or secret manager. If it's ever exposed, revoke it from that same screen and generate a new one.

Authorization: Bearer fxk_a01abde6b4b1b1efb96fa133d831a0fa...

Errors

Errors are returned as JSON with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "invalid_api_secret",
    "message": "This API secret is invalid or has been revoked."
  }
}

Rate limits

Sending messages is limited to 60 requests per minute per bot, since each one triggers an OpenAI call billed to your account. Creating conversations and reading history are not rate limited. If you exceed the limit, you'll get a 429 with code rate_limited — back off and retry.

Get bot info

Returns public information about the bot your API secret belongs to. Useful for rendering a chat header (name, theme) without hardcoding it in your integration.

Example request

curl https://flux-backend-y9vv.onrender.com/api/v1/bots/me \
  -H "Authorization: Bearer fxk_..."

Example response

{
  "id": 24,
  "name": "_luma",
  "company_name": "_luma",
  "theme": "default",
  "language": "es",
  "initial_message": "Hi! I'm Luma from _luma...",
  "active": true
}

Create a conversation

Starts a new conversation for the authenticated bot. If you already know who you're talking to (e.g. a logged-in user on your site), pass their identity here — it's fixed for the lifetime of this conversation and can't be changed by later messages. If the actual person changes mid-conversation, create a new conversation rather than reusing this one.

Any identity you provide is immediately visible to the bot itself — it won't ask the user for their name again if you already passed it here, the same way it already knows a WhatsApp user's profile name and number without asking.

Body parameters

Example request

curl -X POST https://flux-backend-y9vv.onrender.com/api/v1/conversations \
  -H "Authorization: Bearer fxk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Perez",
    "email": "juan@example.com",
    "custom_data": { "plan_interest": "pro" }
  }'

Example response

{
  "conversation_id": "4ccfe5fd-ba65-42c1-a726-b21a3badcf25",
  "created_at": "2026-07-06T17:20:18.874Z"
}

Send a message

Sends a message on behalf of the end user and returns the bot's reply. This runs through the exact same AI pipeline as Fluxy's own web widget and WhatsApp integration — same prompt, same tools, same behavior.

Path parameters

Body parameters

Example request

curl -X POST https://flux-backend-y9vv.onrender.com/api/v1/conversations/4ccfe5fd-ba65-42c1-a726-b21a3badcf25/messages \
  -H "Authorization: Bearer fxk_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "What web services do you offer?" }'

Example response

{
  "conversation_id": "4ccfe5fd-ba65-42c1-a726-b21a3badcf25",
  "message": "We build custom websites, e-commerce platforms..."
}

Note: attaching media_url stores the image and makes it available to specific bot features that expect one (like attaching a photo to a report). The bot does not visually analyze arbitrary images sent in normal conversation — it won't describe what's in a photo unless a feature built for that image explicitly handles it.

Message formatting

The message field returned by Send a message (and by Get message history) is plain text with lightweight Markdown — currently just bold, using double asterisks. Render it with a Markdown parser rather than displaying it as-is, or you'll show the raw asterisks to your users.

"We build **custom websites**, **e-commerce platforms**, and web apps."

Bot replies can also include links in the text (for example, pointing to a product page or a booking confirmation) — by default as a plain URL, e.g. https://example.com/product, rather than Markdown link syntax. Detect and linkify URLs on your end if you want them clickable in your UI.

Get message history

Returns the full message history for a conversation, oldest first. Useful for rebuilding a chat UI after a page refresh.

Path parameters

Example request

curl https://flux-backend-y9vv.onrender.com/api/v1/conversations/4ccfe5fd-ba65-42c1-a726-b21a3badcf25/messages \
  -H "Authorization: Bearer fxk_..."

Example response

{
  "conversation_id": "4ccfe5fd-ba65-42c1-a726-b21a3badcf25",
  "messages": [
    {
      "id": 35749,
      "role": "user",
      "content": "What web services do you offer?",
      "media_url": null,
      "created_at": "2026-07-06T17:20:29.199Z"
    },
    {
      "id": 35750,
      "role": "assistant",
      "content": "We build custom websites, e-commerce platforms...",
      "media_url": null,
      "created_at": "2026-07-06T17:20:36.950Z"
    }
  ]
}