API Reference¶

Complete reference for Fermi API endpoints, in product-journey order: onboarding, connectors, Brain, validation, chat, tasks, forms.

Base URL¶

Most partner APIs:

BASE_URL = "https://api.fermi.dev/public/v1"

Exceptions (full URLs on each page):

Chat & Sessions — https://api.fermi.dev/agents-service/api/v1/agentcore/...
Validation and combined Brain graph — https://api.fermi.dev/core-analytics/...
Forms — https://api.fermi.dev/forms/api
Tasks and SQL schema discovery — https://app.fermi.dev/api/... (Fermi app user session, not a service-actor token)

API Versioning¶

/public/v1/{feature}/{endpoint}

Authentication¶

Authorization: Bearer <service-actor-token>

API keys create organizations and service actors. Service actor tokens access data. Tasks require a Fermi app user session instead.

Learn more: Authentication Guide

Request Format¶

Authorization: Bearer <service-actor-token>
Content-Type: application/json

HTTP Status Codes¶

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
202	Accepted	Async work accepted
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
422	Validation error	Body failed validation
429	Too Many Requests	Rate limit exceeded
500	Server Error	Server error
502	Bad Gateway	Upstream failure (for example, public disconnect)

Feature-Based Endpoints¶

Organization Onboarding ¶

POST /identity/organisations/api-key — Provision an organization (API key)
POST /analytics/chat with "action": "onboarding" and "step": 1 — Partner Q&A (steps 1–5)

Data Connectors ¶

POST /connect/integrations/connect-session — OAuth sessionToken or credential connect
GET /connect/integrations/connections?providerConfigKey= — List connections
POST /sync/enqueue — { connectionId, providerKey } after a real connection exists

Brain ¶

POST /analytics/perform/action — "action": "visualization"
POST /analytics/chat — "action": "graph_modification" with user_input

Validation ¶

GET https://api.fermi.dev/core-analytics/validation/findings — Review findings after connectors

Chat & Sessions ¶

POST https://api.fermi.dev/agents-service/api/v1/agentcore/chat/stream
POST https://api.fermi.dev/agents-service/api/v1/agentcore/chat
GET https://api.fermi.dev/agents-service/api/v1/agentcore/sessions

Tasks ¶

Fermi app session on https://app.fermi.dev/api/tasks. A service-actor token is not sufficient.

Forms ¶

GET https://api.fermi.dev/forms/api/forms/slug/{slug}?tenantId=
POST https://api.fermi.dev/forms/api/forms/{id}/submit

Custom Ontologies ¶

Define ontology vocabularies and apply them during document ingestion.

POST /ontologies - Create ontology
PUT /ontologies/{ontologyId} - Update ontology
POST /ontologies/resolve - Resolve ontology bundle for upload

Authentication ¶

POST /identity/auth/token/exchange — Exchange API key for a service actor token
GET /identity/service-actors — List service actors (API key)

Pagination¶

page (optional): Page number (default: 1)
limit (optional): Items per page, max 50 (default: 10)

Examples¶

cURL Example - Chat Message¶

BASE_URL="https://api.fermi.dev"

curl -X POST "${BASE_URL}/agents-service/api/v1/agentcore/chat/stream" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help me?",
    "session_id": "my-chat-session-123"
  }'

Use session_id from the response for later calls.

Python Example - Brain Visualization¶

import requests

BASE_URL = "https://api.fermi.dev/public/v1"

response = requests.post(
    f"{BASE_URL}/analytics/perform/action",
    headers={
        "Authorization": "Bearer <service-actor-token>",
        "Content-Type": "application/json"
    },
    json={
        "action": "visualization",
        "response_format": "json"
    }
)

if response.status_code == 200:
    data = response.json()
    print(data.get("tenant_id"))
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript Example - List Chat Sessions¶

const BASE_URL = 'https://api.fermi.dev';

const response = await fetch(`${BASE_URL}/agents-service/api/v1/agentcore/sessions?max_results=20`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <service-actor-token>',
    'Content-Type': 'application/json'
  }
});

if (response.ok) {
  const data = await response.json();
  console.log(`Found ${data.sessions.length} sessions`);
} else {
  console.error(`Error: ${response.status} - ${await response.text()}`);
}