For Developers · SDK

Python SDK

Open for contribution

Official FluxChat SDK for Python. Works with Django, FastAPI, Flask, and plain scripts.

Overview

This SDK does not exist yet — you can build it. Use the JS/TypeScript SDK as the reference implementation. The API is identical for all languages — only the syntax changes.

API reference

Ask endpoint

ask.http

POST https://dev-api.fluxchat-corp.com/api/v2/public/bot/ask
Content-Type: application/json
X-API-Key: fc_prod_your_key

{
  "message": "What are your opening hours?",
  "context": "User: Alice, Plan: Pro",    // optional — highest priority
  "conversationId": ""                    // optional — omit for stateless
}

// Response
{
  "success": true,
  "data": {
    "reply": "We are open Mon–Fri 9am–6pm.",
    "conversationId": "conv-uuid",
    "intent": null,
    "confidence": 1
  }
}

Test key

test-key.http

GET https://dev-api.fluxchat-corp.com/api/v2/public/bot/test
X-API-Key: fc_prod_your_key

// Response
{ "success": true, "data": { "organizationId": "org-uuid", "scopes": ["bot:read"] } }

Knowledge base

kb.http

// Create (requires bot:write scope)
POST /api/v2/organizations/{orgId}/knowledge-base
Authorization: X-API-Key fc_prod_your_key
{ "title": "FAQ", "content": "...", "category": "general", "keywords": ["faq"] }

// Update
PATCH /api/v2/organizations/{orgId}/knowledge-base/{id}
{ "content": "Updated content" }

// Delete
DELETE /api/v2/organizations/{orgId}/knowledge-base/{id}

// List / Get (requires JWT admin token)
GET /api/v2/organizations/{orgId}/knowledge-base
GET /api/v2/organizations/{orgId}/knowledge-base/{id}

Usage example — what the SDK should look like

example.python

from fluxchat import FluxChat
import os

client = FluxChat(api_key=os.environ["FLUXCHAT_API_KEY"])

ask.python

response = await client.ask(
    message="What are your opening hours?",
    context="User: Alice, Plan: Pro",
)
print(response.reply)
print(response.conversation_id)

Implementation checklist

Every SDK must implement these features at minimum. Use the TypeScript types in src/types.ts as the reference.

Method	Auth	Description
ask(message, context?, conversationId?)	API key	Send a message, return reply + conversationId
testKey()	API key	Verify the key, return organizationId + scopes
knowledge.create(title, content, ...)	API key (bot:write)	Add a knowledge base article
knowledge.update(id, patch)	API key (bot:write)	Update a KB article
knowledge.delete(id)	API key (bot:write)	Delete a KB article
knowledge.list()	JWT (admin)	List all KB articles
knowledge.get(id)	JWT (admin)	Get one KB article
Error types	—	ApiError, NetworkError, ConfigError with status code

Expected file structure

structure

sdk/python/
├── README.md
├── pyproject.toml
├── fluxchat/
│   ├── __init__.py          # exports FluxChat, errors
│   ├── client.py            # FluxChat class
│   ├── models.py            # AskResponse, KeyInfo, KBArticle
│   └── errors.py            # FluxChatApiError, FluxChatNetworkError
└── tests/
    └── test_client.py

How to contribute

Comment on the GitHub issue to claim it, then follow these steps:

terminal

# 1. Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/fluxchat-sdk.git
cd fluxchat-sdk

# 2. Create your branch
git checkout -b sdk/python

# 3. Add your SDK under sdk/python/
mkdir -p sdk/python

# 4. Implement the checklist, add tests, write a README

# 5. Push and open a PR against main
git push origin sdk/python

View issue #1 on GitHub