MBE API Reference

Version: v2.0 ｜ Updated: 2026-02-11 ｜ Base URL: https://mbe.hi-maker.com

Table of Contents

• 1. Overview
• 2. Authentication
• 3. Chat API (Core)
• 4. Knowledge Base API
• 5. Expert Management API
• 6. Evaluation API
• 7. Benchmark API
• 8. HOPE Preference API
• 9. Audit API
• 10. Webhook Events
• 11. Error Handling
• 12. Rate Limiting

1. Overview

Base Information

Common Response Format

Success:

{
  "success": true,
  "data": { "..." },
  "message": "Operation successful"
}

Error:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error description",
  "detail": "Detailed info (dev environment only)"
}

2. Authentication

API Key Authentication

All API calls require the Authorization header:

Authorization: Bearer YOUR_API_KEY

Or use the X-API-Key header:

X-API-Key: YOUR_API_KEY

Get Your API Key

1. Log in to the Developer Console
2. Navigate to Settings → API Keys
3. Click Generate New Key

Rate Limits by Plan

3. Chat API (Core)

Ask an Expert

POST /api/expert/ask

Request:

{
  "query": "What are the legal consequences of breach of contract?",
  "expert_id": "exp_abc123",
  "conversation_id": "conv_xyz",
  "options": {
    "show_references": true,
    "zero_retention": false
  }
}

Response:

{
  "success": true,
  "data": {
    "answer": "The legal consequences of breach of contract include...",
    "expert": "Civil Law Expert",
    "confidence": 0.92,
    "conversation_id": "conv_xyz",
    "sources": [
      {"name": "Civil Code Art. 577", "confidence": 0.95, "excerpt": "..."}
    ],
    "self_critique": {
      "passed": true,
      "modules_triggered": ["SC-2", "SC-6"]
    }
  }
}

Multi-turn Conversation

# Turn 1
resp1 = client.post("/api/expert/ask", json={
    "query": "What is the standard for economic compensation?",
    "expert_id": "legal_001"
})
conv_id = resp1.json()["data"]["conversation_id"]

# Turn 2 (references previous context)
resp2 = client.post("/api/expert/ask", json={
    "query": "What about the case where the employee refuses renewal?",
    "expert_id": "legal_001",
    "conversation_id": conv_id
})

4. Knowledge Base API

Upload Document

POST /api/experts/{expert_id}/knowledge-base
Content-Type: multipart/form-data

List Documents

GET /api/experts/{expert_id}/knowledge-base

Delete Document

DELETE /api/experts/{expert_id}/knowledge-base/{doc_id}

5. Expert Management API

Create Expert

POST /api/experts

{
  "name": "Legal Advisor",
  "description": "Specializing in civil and commercial law",
  "definition_prompt": "You are an experienced legal advisor...",
  "industry": "legal",
  "self_critique_config": {
    "enabled_modules": ["SC-1", "SC-2", "SC-3", "SC-6", "SC-12", "SC-13"]
  }
}

List Experts

GET /api/experts

Get Expert Details

GET /api/experts/{expert_id}

Update Expert

PUT /api/experts/{expert_id}

Publish Expert

POST /api/experts/{expert_id}/publish

Delete Expert

DELETE /api/experts/{expert_id}

6. Evaluation API

Run Gate Check

POST /api/evaluation/gate
{"expert_id": "exp_abc123"}

Response:

{
  "gate_result": "PASS",
  "checks": [
    {"name": "basic_qa", "result": "pass", "score": 0.85},
    {"name": "safety", "result": "pass", "score": 0.95}
  ],
  "can_publish": true
}

Get Net Score

GET /api/evaluation/net-score/{expert_id}

Response:

{
  "expert_id": "exp_abc123",
  "net_score": 0.82,
  "correct_rate": 0.88,
  "incorrect_rate": 0.06,
  "uncertain_rate": 0.06,
  "calibration_score": 0.50
}

Run Multi-turn Safety Test

POST /api/evaluation/multi-turn-safety
{
  "expert_id": "exp_abc123",
  "industry_filter": "legal",
  "randomization_runs": 3
}

7. Benchmark API

Run 6-Dimension Benchmark

POST /api/evaluation/benchmark/run
{
  "expert_id": "exp_abc123",
  "dimensions": ["accuracy", "hallucination", "safety", "citation", "quality", "consistency"],
  "num_trials": 3
}

Dimensions:

8. HOPE Preference API

Enable HOPE

PUT /api/experts/{expert_id}/hope
{
  "enabled": true,
  "learning_rate": "moderate",
  "preference_dimensions": ["response_length", "formality_level", "detail_depth"]
}

Get HOPE Status

GET /api/experts/{expert_id}/hope/status

9. Audit API

Audit Single Conversation

POST /api/audit/conversation
{
  "expert_id": "exp_abc123",
  "conversation": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "industry": "legal"
}

Generate Audit Report

POST /api/audit/report
{
  "expert_id": "exp_abc123",
  "period_days": 7
}

Get Alerts

GET /api/audit/alerts?expert_id=exp_abc123

Audit Metrics

10. Webhook Events

Supported Events

Webhook Payload

{
  "event": "expert.quarantined",
  "timestamp": "2026-02-11T10:00:00Z",
  "data": {
    "expert_id": "exp_abc123",
    "reason": "behavioral_audit",
    "severity": "CRITICAL"
  }
}

11. Error Handling

Error Codes

Prompt Injection Response (403)

When L1 input filter detects injection:

{
  "success": false,
  "error": "prompt_injection_detected",
  "message": "Request blocked by security system",
  "risk_level": "HIGH"
}

Response header: X-Injection-Warning: HIGH

12. Rate Limiting

Headers

Retry Strategy

import time

def call_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)
    raise Exception("Rate limit exceeded after retries")

See also: 中文版 API 文档 · Getting Started (EN) · SDK Examples