Skip to content

REST API

REST is not part of the hosted product today

The hosted product is reached over MCP. Every /api/v1/* route documented on this page is closed at the edge: the production nginx config answers location /api/ with 404 (see infra/nginx/conf.d.prod/g6solver.conf). The examples below will not work against g6solver.com — they are kept as engineering reference for the REST base in this repository, not as customer instructions.

The G6 REST API is a FastAPI application exposing all core operations as HTTP/JSON endpoints. It serves as the primary web integration interface.

Base URL

Environment URL
Local dev http://localhost:8010
Production (closed — /api/ returns 404 at the edge)

Authentication

Production endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Local development runs without authentication by default.

Core endpoints

Health check

GET /health

Response: 

{
  "status": "ok",
  "system": "G6 Hyperdistillation",
  "version": "0.1.0"
}

List components

GET /components

Returns all registered components from the component registry.

Response: 

{
  "components": ["core", "goal_engine", "formal_methods", "adapt_sklearn", ...]
}

List blocks

GET /blocks

Alias for /components. Returns the same registry data.

Clusters

The REST API uses a manifest-driven cluster system. Components are grouped into thematic clusters, and each visible cluster is exposed as a set of REST routes. Hidden/infrastructure clusters (core-infrastructure, safety-alignment, formal-verification, cognitive-architectures, knowledge-grounding, self-optimisation, agents-llm) are not exposed via the REST API.

List clusters

GET /clusters

Returns all visible clusters with their components.

Response: 

{
  "ok": true,
  "clusters": [
    {
      "slug": "context-retrieval",
      "display_name": "Context Retrieval",
      "description": "Search, scrape, parse, and retrieve context from documents, the web, and vector stores.",
      "components": ["ctx_rag", "ctx_colbert", "ctx_elastic", "ctx_search", "..."]
    }
  ]
}

Cluster detail

GET /clusters/{slug}

Response: 

{
  "ok": true,
  "slug": "ml-optimisation",
  "display_name": "ML & Optimisation",
  "description": "Machine learning, Bayesian inference, evolutionary algorithms, and hyperparameter optimisation.",
  "components": ["adapt_sklearn", "adapt_bayesian", "adapt_optimisation", "..."]
}

Returns 404 if the cluster slug is not found.

Invoke a component within a cluster

POST /clusters/{slug}/{component}

Request body: 

{
  "op": "classify",
  "params": {"X": [[1, 2], [3, 4]], "y": [0, 1]}
}

Response: 

{
  "ok": true,
  "result": { "..." : "..." },
  "cluster": "ml-optimisation",
  "component": "adapt_sklearn"
}

Returns 404 if the cluster or component is not found. The component must belong to the specified cluster.

Visible clusters

Slug Components Description
context-retrieval 12 Search, scrape, parse, and retrieve context
ml-optimisation 11 ML, Bayesian inference, evolutionary algorithms
data-processing 3 Tabular data, structured extraction, task queues
code-intelligence 8 Code generation, meta-programming, self-healing
goal-planning 6 Goal decomposition, constraint solving, navigation
creative-media 11 Audio, video, image, 3D, UI design
physical-ai 8 Robotics, motor control, embodiment, physics
multimodal 2 Multimodal reasoning and transformer retrieval
job-agents 38 Specialised autonomous job agents

Dynamic component invocation

Invoke any component

POST /invoke/{component}

Request body: 

{
  "op": "search",
  "params": {"query": "machine learning"}
}

Response: 

{
  "ok": true,
  "result": { ... }
}

Run a pipeline

POST /pipeline

Request body: 

{
  "steps": [
    {"component": "ctx_search", "op": "search", "params": {"query": "AI safety"}},
    {"component": "ctx_rag", "op": "retrieve", "params": {}},
    {"component": "ctx_recursive", "op": "summarise", "params": {}}
  ],
  "initial": {"query": "AI safety"}
}

Response: 

{
  "ok": true,
  "result": { ... }
}

Discover components

GET /nav/discover?query=sentiment+analysis&limit=20

Recommend components

GET /nav/recommend?query=classify+images&limit=5

Inspect a component

GET /nav/inspect/{component}

GET /nav/stats

Guide routes

Ask the guide

POST /guide/ask

Request body: 

{
  "query": "How do I run a safety check?",
  "top_k": 5
}

Plan a workflow

POST /guide/plan

Request body: 

{
  "goal": "Analyze CSV data and train a model",
  "max_steps": 5
}

System overview

GET /guide/overview

Template pipelines

Research pipeline

POST /pipeline/research

Chains: ctx_search -> ctx_rag -> ctx_recursive

Code generation pipeline

POST /pipeline/codegen

Chains: meta_programming -> formal_methods -> align_evals

Data pipeline

POST /pipeline/data

Chains: adapt_pandas -> adapt_sklearn -> align_evals

Safety pipeline

POST /pipeline/safety

Chains: align_csf -> formal_methods -> grounding

Admin

Reload security policy

POST /admin/reload-policy

Reloads the RBAC security policy from disk. Requires admin permissions.

Response: 

{
  "ok": true,
  "message": "Policy reloaded"
}

Client examples

Copy-paste examples for the most common operations. Replace YOUR_API_KEY with your actual key (production only — local dev needs no auth).

Health check

curl -s http://localhost:8010/health | python -m json.tool

import httpx

r = httpx.get("http://localhost:8010/health")
print(r.json())
# {"status": "ok", "system": "G6 Hyperdistillation", "version": "0.1.0"}

const r = await fetch("http://localhost:8010/health");
const data = await r.json();
console.log(data);
// {status: "ok", system: "G6 Hyperdistillation", version: "0.1.0"}

Invoke a component

curl -X POST http://localhost:8010/invoke/ctx_search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"op": "search", "params": {"query": "AI safety frameworks"}}'

import httpx

r = httpx.post(
    "http://localhost:8010/invoke/ctx_search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"op": "search", "params": {"query": "AI safety frameworks"}},
)
print(r.json()["result"])

const r = await fetch("http://localhost:8010/invoke/ctx_search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({op: "search", params: {query: "AI safety frameworks"}}),
});
const data = await r.json();
console.log(data.result);

Run a pipeline

curl -X POST http://localhost:8010/pipeline \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "steps": [
      {"component": "ctx_search", "op": "search", "params": {"query": "quantum computing"}},
      {"component": "ctx_rag", "op": "retrieve", "params": {}},
      {"component": "ctx_recursive", "op": "summarise", "params": {}}
    ],
    "initial": {"query": "quantum computing"}
  }'

import httpx

pipeline = {
    "steps": [
        {"component": "ctx_search", "op": "search", "params": {"query": "quantum computing"}},
        {"component": "ctx_rag", "op": "retrieve", "params": {}},
        {"component": "ctx_recursive", "op": "summarise", "params": {}},
    ],
    "initial": {"query": "quantum computing"},
}
r = httpx.post(
    "http://localhost:8010/pipeline",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=pipeline,
)
print(r.json()["result"])

const pipeline = {
  steps: [
    {component: "ctx_search", op: "search", params: {query: "quantum computing"}},
    {component: "ctx_rag", op: "retrieve", params: {}},
    {component: "ctx_recursive", op: "summarise", params: {}},
  ],
  initial: {query: "quantum computing"},
};
const r = await fetch("http://localhost:8010/pipeline", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify(pipeline),
});
console.log((await r.json()).result);

Ask the guide

curl -X POST http://localhost:8010/guide/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I run a safety check on my code?", "top_k": 3}'

import httpx

r = httpx.post(
    "http://localhost:8010/guide/ask",
    json={"query": "How do I run a safety check on my code?", "top_k": 3},
)
print(r.json())

const r = await fetch("http://localhost:8010/guide/ask", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({query: "How do I run a safety check on my code?", top_k: 3}),
});
console.log(await r.json());

Discover components

curl "http://localhost:8010/nav/recommend?query=classify+images&limit=5"

import httpx

r = httpx.get("http://localhost:8010/nav/recommend", params={"query": "classify images", "limit": 5})
for comp in r.json().get("recommendations", []):
    print(f"  {comp['name']}: {comp['description']}")

const r = await fetch("http://localhost:8010/nav/recommend?query=classify+images&limit=5");
const data = await r.json();
data.recommendations.forEach(c => console.log(`  ${c.name}: ${c.description}`));

Error handling

All endpoints return a consistent error shape:

{
  "ok": false,
  "error": "Descriptive error message"
}

HTTP status codes follow standard conventions:

Code Meaning
200 Success
401 Invalid or missing API key
403 Security denial (gateway blocked the request)
404 Unknown endpoint or component
422 Validation error (Pydantic)
429 Rate limit exceeded
500 Internal server error

Deployment

# Local development
python -m mvp.rest

# Production (uvicorn)
uvicorn mvp.rest:app --host 0.0.0.0 --port 8010

See also