For Developers · SDK

Swift SDK (iOS / macOS)

Open for contribution

Native Swift SDK with async/await for iOS and macOS applications.

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.swift

import FluxChatSDK

let client = FluxChatClient(
    apiKey: ProcessInfo.processInfo.environment["FLUXCHAT_API_KEY"]!
)

ask.swift

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

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/swift/
├── README.md
├── Package.swift
├── Sources/FluxChatSDK/
│   ├── FluxChatClient.swift
│   ├── Models.swift         # AskResponse, KBArticle, KeyInfo
│   └── Errors.swift         # FluxChatError, APIError
└── Tests/FluxChatSDKTests/
    └── FluxChatClientTests.swift

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/swift

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

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

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

View issue #6 on GitHub