Server Examples

Usage and Examples¶

In this section, we'll walk through how to use the MindFlight AI Server in real-life scenarios. We'll start with simple API requests and gradually move to more advanced use cases.

1️⃣ Authentication¶

Before using the server, Clients must authenticate to get a token. This token is required to access protected API endpoints.

Example: Requesting a Token

curl -X POST http://localhost:8080/api/login \
    -H "Content-Type: application/json" \
    -d '{"username": "testuser", "password": "testpassword"}'

✅ What you get: A JSON response like:

{
    "token": "eyJhbGciOiJIUzI1NiIsIn..."
}

Use this token in the Authorization header for future requests.

2️⃣ Chat API Example¶

Let's send a simple chat request using the token.

curl -X POST http://localhost:8080/api/chat \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{"message": "Hello, MindFlight AI!"}'

✅ Response:

{
    "reply": "Hello! How can I assist you today?"
}

Metaphor: Like texting your AI assistant and getting an instant reply.

3️⃣ Running a Provider Tool¶

Suppose you have the Filesystem Provider enabled and want to list files in a directory.

Example: List Files

curl -X POST http://localhost:8080/api/tools/filesystem_list_files \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{"directory": "/tmp"}'

✅ Response:

{
    "files": ["file1.txt", "file2.txt"]
}

4️⃣ Storing and Retrieving Memory¶

You can store key-value pairs in the server's memory for later use.

Example: Set a Memory Value

curl -X POST http://localhost:8080/api/memory/set \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{"key": "favorite_color", "value": "blue"}'

Example: Get a Memory Value

curl -X GET "http://localhost:8080/api/memory/get?key=favorite_color" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE"

✅ Response:

{
    "key": "favorite_color",
    "value": "blue"
}

5️⃣ Subscribing to Notifications¶

You can subscribe to events using webhooks to get real-time updates.

Example: Subscribe to an Event

curl -X POST http://localhost:8080/api/notifications/subscribe \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
        "event": "email.processed",
        "callback_url": "https://yourapp.com/webhook/email"
    }'

✅ Now, every time an email.processed event happens, the server will POST data to your callback_url.

6️⃣ Monitoring a Job¶

Some tasks are long-running and are processed as background jobs.

Example: Check Job Status

curl -X GET http://localhost:8080/api/jobs/status/{job_id} \
    -H "Authorization: Bearer YOUR_TOKEN_HERE"

✅ Response:

{
    "job_id": "abc123",
    "status": "completed",
    "result": { ... }
}

Metaphor: It's like ordering a pizza and tracking its status: "preparing", "baking", "out for delivery", "delivered".

7️⃣ Go Client Example (Bonus)¶

Here's a simple Go snippet showing how to send a chat message programmatically.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    token := "YOUR_TOKEN_HERE"
    message := map[string]string{"message": "Hello, AI!"}
    body, _ := json.Marshal(message)

    req, _ := http.NewRequest("POST", "http://localhost:8080/api/chat", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println("Response:", result)
}

Quick Recap¶

Task	Endpoint
Authenticate	`/api/login`
Chat	`/api/chat`
Run a Provider Tool	`/api/tools/{tool_name}`
Set/Get Memory	`/api/memory/set`, `/api/memory/get`
Subscribe to Notifications	`/api/notifications/subscribe`
Check Job Status	`/api/jobs/status/{job_id}`