MindFront Fiber Quick Start

4 min read

For MindFront Fiber V4

MindFront connects to your company’s most valuable tools and data.

MindFront Fiber is how—and it’s incredibly easy to get started.

You create a simple web service, and its functions become new abilities that your MindFront can use.

MindFront Fiber is powerful because it’s simple. There are no required SDKs. You use the tools you already know. Your code stays fully private and fully yours.

This is a quick-start guide to get something in 5 minutes. Definitely provide it to MindFront, ChatGPT or whatever AI system you are using!

How it works

sequenceDiagram
    participant SG as MindFront
    participant YS as Your Service

    SG->>YS: GET /meta
    YS-->>SG: Here's what I can do
    SG->>YS: POST /your/endpoint
    YS-->>SG: Here's the result

What You Need To Build

A Meta endpoint (GET /meta) that describes what your service can do.
Action endpoints (optional) that perform tasks and return JSON.
An Events endpoint (optional) that streams business events MindFront drains on a poll.

1. Meta Endpoint

A GET endpoint at /meta tells MindFront what your module can do.

Example Response:

{
  "protocolVersion": 4,
  "moduleVersion": "1.0.0",
  "moduleName": "MyService",
  "description": "A brief description of this service.",
  "actions": [
    {
      "name": "doSomething",
      "description": "Does something useful.",
      "route": "/action/doSomething",
      "riskLevel": "humanApprovalRequired",
      "pictogram": "automation",
      "typicalHumanProcessTimeInMinutes": 5,
      "input": {
        "type": "object",
        "properties": {
          "param1": {"type": "string"}
        }
      }
    }
  ]
}

input defines the parameters you want MindFront to provide for you.
pictogram (optional) sets a Carbon Design icon for the action in the UI.
typicalHumanProcessTimeInMinutes (optional) tells MindFront how many minutes this would take a human, so it can show time savings.

2. Action Endpoints

These are POST endpoints that do something useful, like perform a task or get some data. They receive JSON and must return JSON.

Success Response:

{
  "status": "success",
  "data": { "result": "The action was successful." },
  "tldr": "A short summary of what just happened.",
  "attachment_urls": []
}

tldr (optional) is a short human-readable line that MindFront shows as the action’s success summary in the UI.
attachment_urls (optional) is an array of URLs MindFront fetches and ingests into the document store as file deliverables on the outcome.

Error Response:

{
  "status": "failure",
  "error": { "message": "Something went wrong." }
}

3. Events Endpoint (Optional)

If your module exposes a GET /events endpoint and sets "servesEvents": true in /meta, MindFront polls it every few seconds and drains each response — events are delivered exactly once and you own the cursor. Return [] when nothing new has arrived. See the full spec for the event schema.

Complete Working Example

This minimal Python server correctly implements the protocol.

#!/usr/bin/env python3
import json
from http.server import HTTPServer, BaseHTTPRequestHandler

# Define what your module does
METADATA = {
    "protocolVersion": 4,
    "moduleVersion": "1.0.0",
    "moduleName": "HelloWorld",
    "description": "A simple example module that says hello.",
    "actions": [
        {
            "name": "sayHello",
            "description": "Says hello to someone.",
            "route": "/action/sayHello",
            "riskLevel": "safe",
            "pictogram": "hello",
            "typicalHumanProcessTime": 5,
            "input": {
                "type": "object",
                "properties": {"name": {"type": "string"}},
                "required": ["name"]
            }
        }
    ],
    "data": []
}

# The handler for your server
class FiberHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        # Handle the /meta endpoint
        if self.path == "/meta":
            self.send_response(200)
            self.send_header("Content-type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps(METADATA).encode())
        else:
            self.send_error(404)

    def do_POST(self):
        # Handle the /action/sayHello endpoint
        if self.path == "/action/sayHello":
            try:
                # Read and parse the JSON input
                content_length = int(self.headers['Content-Length'])
                post_data = self.rfile.read(content_length)
                input_data = json.loads(post_data)

                # Prepare the success response
                name = input_data.get('name', 'World')
                response_data = {
                    "status": "success",
                    "data": {"message": f"Hello, {name}!"}
                }
                
                # Send the success response
                self.send_response(200)
                self.send_header("Content-type", "application/json")
                self.end_headers()
                self.wfile.write(json.dumps(response_data).encode())

            except Exception as e:
                # On failure, return a JSON error body.
                # A 200 status code is fine here because the transport (HTTP) succeeded. MindFront will check the body.
                self.send_response(200)
                self.send_header("Content-type", "application/json")
                self.end_headers()
                error_data = {"status": "failure", "error": {"message": str(e)}}
                self.wfile.write(json.dumps(error_data).encode())
        else:
            self.send_error(404)

# Run the server
if __name__ == "__main__":
    print("Starting MindFront Fiber server on http://localhost:8080")
    HTTPServer(("", 8080), FiberHandler).serve_forever()

Test It

Run the Python script: python3 your_script_name.py

In another terminal, test the endpoints:

# Get the metadata
curl "http://localhost:8080/meta"

# Call the action
curl -X POST "http://localhost:8080/action/sayHello" \
     -H "Content-Type: application/json" \
     -d '{"name": "Sarah Connor"}'

Connecting to MindFront

To connect your running MindFront Fiber service, ask your MindFront administrator for assistance.

That’s It.

Need more details? See the full specification.