REFERENCE

WEB6 API Reference

One API, every AI. All 35+ endpoints of the OASIS WEB6 unified AI gateway — request shapes, field types, and response structures.

BASE URL https://api.web6.oasisomniverse.one
Authentication: All endpoints require Authorization: Bearer <JWT>  or  X-Api-Key: <key>. Get yours at OPORTAL.

Completions

POST /v1/complete
Routes a chat completion to the best-fit AI provider for your plan. Optionally enhances the request with FAHRN reasoning dispatch and Holonic BRAID graph injection.
Request body
FieldTypeDescription
messagesrequiredarrayArray of {"role":"user|assistant|system","content":"..."} objects
providerstringTarget provider: openai, anthropic, gemini, groq, mistral, cohere, xai, deepseek, ollama, awsbedrock, azureopenai, auto (default)
modelstringModel ID e.g. gpt-4o, claude-sonnet-5. Default: auto
avatarIdstring (uuid)OASIS avatar ID for karma-gated access and usage metering
useFAHRNbooleanRun the last user message through the FAHRN reasoning network and inject the plan into context
useHolonicBraidbooleanInject the shared Holonic BRAID reasoning graph for the detected task type
injectAvatarContextbooleanPrepend this avatar's identity/karma context to the system prompt
toolsarrayTool definitions (OpenAI-compatible function calling schema)
temperaturenumber0–2. Default provider-specific
maxTokensintegerMax completion tokens
routingobjectAdvanced routing overrides e.g. {"useOpenServ":true}
Example
{
  "provider": "auto",
  "model": "auto",
  "messages": [
    {"role": "system", "content": "You are a helpful OASIS guide."},
    {"role": "user", "content": "What is holonic memory?"}
  ]
}
POST /v1/complete/stream
Same as /v1/complete but returns a text/event-stream SSE response. Each data: line is a JSON completion chunk; the final chunk has "done":true.
Response format (SSE)
data: {"content":"Once ","done":false}
data: {"content":"upon ","done":false}
data: {"content":"a time...","done":false}
data: {"content":"","done":true,"promptTokens":12,"completionTokens":47}
POST /v1/complete/tool-result
Re-enters the completion pipeline with a message history that already contains role:"tool" result messages. Use this for agentic tool-calling loops.

Embeddings

POST /v1/embeddings
Generates vector embeddings for one or more text strings.
FieldTypeDescription
textsrequiredstring[]One or more strings to embed
providerstringe.g. openai, cohere, auto
modelstringe.g. text-embedding-3-large

Image Generation

POST /v1/images/generate
Generates images from text prompts via DALL·E 3, Stable Diffusion, Midjourney and others.
FieldTypeDescription
promptrequiredstringImage description
providerstringe.g. openai, stability, auto
widthintegerOutput width in pixels
heightintegerOutput height in pixels
nintegerNumber of images (default 1)

Video Generation

POST /v1/video/generate
Generates video from text or image via RunwayML, Luma AI, Pika Labs, Kling AI, HailuoAI (MiniMax), Vidu, Wan Video. Long-running — supply callbackUrl for webhook notification.
FieldTypeDescription
promptrequiredstringVideo description
providerstringe.g. runwayml, lumaai, auto
imageUrlstringSeed image URL for image-to-video
durationintegerDuration in seconds
aspectRatiostringe.g. 16:9, 9:16, 1:1
callbackUrlstringWebhook URL to receive completion POST when rendering finishes

Audio

POST /v1/audio/speech
Synthesises speech from text (TTS). Returns audio bytes.
FieldTypeDescription
textrequiredstringText to synthesise
voicestringVoice ID e.g. alloy, nova, shimmer
providerstringe.g. openai, elevenlabs, auto
POST /v1/audio/transcriptions
Transcribes audio to text (STT) via Whisper or compatible providers. Accepts multipart form with an audio file.
FieldTypeDescription
filerequiredmultipart fileAudio file (.mp3, .wav, .m4a, etc.)
languagestringISO-639-1 code e.g. en, fr

Reranking

POST /v1/rerank
Reranks a list of documents by relevance to a query via Cohere Rerank or compatible providers.
FieldTypeDescription
queryrequiredstringQuery to rank against
documentsrequiredstring[]Documents to rerank
topNintegerNumber of top results to return (default 5)
providerstringe.g. cohere, auto

Moderation

POST /v1/moderation
Checks text for harmful, unsafe or policy-violating content.
FieldTypeDescription
textrequiredstringText to check
providerstringe.g. openai, llamaguard, auto

Translation

POST /v1/translate
Translates text to a target language via DeepL, Google Translate, or LLM-backed providers.
FieldTypeDescription
textrequiredstringSource text
targetLanguagerequiredstringISO-639-1 e.g. fr, de, ja
sourceLanguagestringAuto-detected if omitted
providerstringe.g. deepl, googletranslate, auto

Classification

POST /v1/classify
Zero-shot text classification against a user-supplied label set.
FieldTypeDescription
textrequiredstringText to classify
labelsrequiredstring[]Candidate labels e.g. ["positive","negative","neutral"]
providerstringe.g. cohere, auto

Structured Extraction

POST /v1/extract
Extracts structured data from unstructured text according to a JSON schema.
FieldTypeDescription
textrequiredstringSource text
schemarequiredobjectJSON schema describing the target structure
providerstringe.g. openai, auto

Document Processing

POST /v1/documents/parse
Parses PDFs, Word docs, and other document formats into structured text. Accepts multipart form.
FieldTypeDescription
filerequiredmultipart fileDocument file (.pdf, .docx, .txt, etc.)
providerstringe.g. llamaparse, auto

Code Execution

POST /v1/code/execute
Executes code in a sandboxed environment and returns output.
FieldTypeDescription
coderequiredstringCode to execute
languagestringpython, javascript, bash (default: python)
providerstringExecution sandbox provider

Batch Processing

POST /v1/batch/submit
Submits a batch of completion requests at up to 50% cost reduction via OpenAI Batch API or Anthropic Message Batches. Supply callbackUrl for webhook notification when complete.
FieldTypeDescription
requestsrequiredarrayArray of completion request objects
providerstringe.g. openai, anthropic, auto
callbackUrlstringWebhook URL for completion notification
GET /v1/batch/{batchId}/status
Polls a previously submitted batch job for status and results.
ParamTypeDescription
batchIdpath stringBatch ID returned by /v1/batch/submit
providerquery stringProvider that owns the batch job

Memory

POST /v1/memory/store
Stores a memory fragment for later retrieval via Mem0, Zep, Qdrant, Weaviate, or built-in OASIS holonic memory.
FieldTypeDescription
contentrequiredstringContent to store
userIdstringUser/avatar identifier
providerstringe.g. mem0, zep, auto
POST /v1/memory/query
Semantic search over stored memories for a given user.
FieldTypeDescription
queryrequiredstringQuery to search
userIdstringScope to a specific user
providerstringMemory provider

Guardrails

POST /v1/guardrails/check
Checks text against safety and policy guardrails via NeMo Guardrails or compatible providers.
FieldTypeDescription
textrequiredstringInput to check
providerstringe.g. nemo, auto

Fine-Tuning

POST /v1/fine-tuning/jobs
Creates a fine-tuning job. Supply callbackUrl to receive a webhook when training completes.
FieldTypeDescription
baseModelrequiredstringBase model ID to fine-tune
trainingDatarequiredarrayArray of training examples
providerstringe.g. openai, togetherai, mistral
callbackUrlstringWebhook URL for training completion
GET /v1/fine-tuning/jobs/{jobId}
Gets the status of a fine-tuning job.

GraphRAG

POST /v1/graphrag/query
Graph-based retrieval-augmented generation — answers complex multi-hop questions using a knowledge graph.
FieldTypeDescription
queryrequiredstringNatural language query
providerstringe.g. thegraph, neo4j, auto

Prompt Optimisation

POST /v1/prompts/optimise
Automatically rewrites and improves a prompt using SkillOpt or LLM-based optimisation.
FieldTypeDescription
promptrequiredstringOriginal prompt
providerstringOptimisation provider

FAHRN — Reasoning Network

POST /v1/reasoning-network/dispatch
Dispatches a problem through the Fractal Adaptive Holonic Reasoning Network — classifies the task, scores agents, assembles the optimal sub-network, and returns a final answer with a Mermaid execution plan.
FieldTypeDescription
problemrequiredstringThe problem or question to solve
taskTypestringTask hint e.g. general, code, research, creative
modestringSerial (default), Parallel, Hybrid

Model Catalogue

GET /v1/models
Lists all 23+ models in the WEB6 catalogue with pricing, context window, and minimum plan requirement.
ParamTypeDescription
planquery stringFilter to models accessible on this plan: Free, Bronze, Silver, Gold
Example response
{
  "total": 23,
  "models": [
    {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "providerName": "OpenAI",
      "minPlanLabel": "Bronze",
      "inputPer1kUSD": 0.0025,
      "outputPer1kUSD": 0.01,
      "contextWindow": 128000,
      "supportsVision": true,
      "supportsFunctions": true
    }
  ]
}
GET /v1/models/{modelId}
Returns full detail for a single model.

Provider Status

GET /v1/providers
Returns all 99 providers with their minimum plan requirement, supported endpoint types, and live status.

Cost Estimate

POST /v1/estimate
Previews the estimated USD cost of a call before executing it, based on token counts and the provider's current pricing.
FieldTypeDescription
providerrequiredstringProvider ID e.g. openai
modelrequiredstringModel ID e.g. gpt-4o
promptTokensrequiredintegerExpected prompt token count
completionTokensintegerExpected completion token count (default 0)
Response
{ "estimatedUSD": 0.001250, "note": "Based on gpt-4o pricing at $0.0025/1K in + $0.01/1K out" }

Usage

GET /v1/usage
Returns this avatar's usage summary — daily calls used, effective call limit (plan × karma multiplier), monthly token spend, and remaining quota today.
ParamTypeDescription
planquery stringSubscription plan for limit calculation: Free, Bronze, Silver, Gold, Enterprise
karmaquery integerAvatar karma score for multiplier calculation
Response
{
  "dailyCallsUsed": 47,
  "dailyCallLimit": 1500,
  "remainingCallsToday": 1453,
  "karmaMultiplier": 3.0,
  "monthlySpendUSD": 0.042,
  "dailyTokensUsed": 185000,
  "periodMonth": "2026-08",
  "periodDay": "2026-08-23"
}

Health

GET /v1/health
Unauthenticated status check. Returns API version and UTC timestamp. Used by load balancers and uptime monitors.
Response
{
  "status": "ok",
  "version": "2.0",
  "timestamp": "2026-08-23T10:00:00.0000000Z"
}

OpenServ

GET /v1/openserv/models
Returns all WEB6 models in OpenServ-compatible format. Use this when connecting WEB6 as an OpenServ AI provider — OpenServ fetches this endpoint to populate its model selector.
Response
[
  {
    "id": "oasis-web6/gpt-4o",
    "name": "GPT-4o via WEB6",
    "provider": "openai",
    "contextWindow": 128000,
    "capabilities": ["chat", "tools", "vision"]
  },
  ...
]

Orchestrators

Route multi-agent orchestration frameworks through WEB6. Each endpoint translates a framework-native payload into WEB6 completions and returns results in the originating framework's expected shape — no framework SDK required.

POST /v1/orchestrate/crewai
Dispatches a CrewAI-style crew definition. WEB6 maps each agent's role to the best provider for that capability tier and runs tasks in the specified process order.
FieldTypeDescription
tasksrequiredarrayArray of task objects with id, agent, description, expected_output
processstringsequential (default) or hierarchical
providerstringForce all agents to a specific WEB6 provider (default: auto)
Example
{
  "process": "sequential",
  "tasks": [
    {
      "id": "research",
      "agent": "Researcher",
      "description": "Find the top 3 OASIS providers for video generation",
      "expected_output": "A ranked list with reasons"
    },
    {
      "id": "write",
      "agent": "Writer",
      "description": "Turn the research findings into a blog section",
      "expected_output": "200-word blog paragraph"
    }
  ]
}
POST /v1/orchestrate/autogen
Accepts a Microsoft AutoGen conversation initiation payload. Routes the initial_message through WEB6 and returns a reply in AutoGen's expected assistant-message shape.
FieldTypeDescription
initial_messagerequiredstringThe opening user message to start the AutoGen conversation
system_messagestringSystem/assistant persona to set for the WEB6 agent
providerstringWEB6 provider to use (default: auto)
modelstringModel ID override (default: auto)
max_roundsintegerMaximum conversation rounds (default: 10)
POST /v1/orchestrate/langgraph
Receives a LangGraph node invocation — the current graph state plus the node to execute. Runs the node's LLM step via WEB6 and returns the updated state for the next graph edge.
FieldTypeDescription
node_namerequiredstringThe LangGraph node identifier to execute
stateobjectCurrent graph state (key-value pairs, passed through and augmented)
messagesarrayMessage history to pass to the LLM for this node
next_nodestringNext node to route to (returned in response for the graph executor)
providerstringWEB6 provider (default: auto)
Response
{
  "isError": false,
  "result": {
    "state": {
      "research_output": "...",
      "__node__": "research",
      "__timestamp__": "2026-08-23T10:00:00Z"
    },
    "nextNode": "summarise"
  }
}

MCP — Model Context Protocol

WEB6 exposes its full capability surface as an MCP server, making every tool callable directly from Claude Code, claude.ai connectors, OpenAI Responses API, and any other MCP-compatible client — with zero HTTP configuration required.

MCP ENDPOINT https://api.web6.oasisomniverse.one/mcp
DISCOVERY DOCUMENTS https://api.web6.oasisomniverse.one/.well-known/mcp.json
https://api.web6.oasisomniverse.one/.well-known/agent.json

Connect in Claude Code:

claude mcp add oasis-web6 \
  --transport http \
  --url https://api.web6.oasisomniverse.one/mcp \
  --header "Authorization: Bearer <your-jwt>"

Or in ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "oasis-web6": {
      "transport": "http",
      "url": "https://api.web6.oasisomniverse.one/mcp",
      "headers": { "Authorization": "Bearer <your-jwt>" }
    }
  }
}

MCP Tool Reference

All 35+ tools exposed by the MCP server. Each tool is callable from any MCP client — Claude Code, claude.ai, OpenAI, or your own agent.

Tool nameWhat it does
web6_completeChat completion across 99 providers (auto-routes)
web6_fahrn_solveFull FAHRN pipeline — classify, dispatch, BRAID, EMA, telemetry in one call
web6_fahrn_dispatchDirect FAHRN dispatch with explicit mode (Serial/Parallel/Decomposed)
web6_fahrn_register_agentRegister a new reasoning agent with FAHRN
web6_fahrn_get_agentsList all FAHRN agents with live composite scoring
web6_fahrn_seed_openserv_agentsSeed FAHRN with one agent per OpenServ SERV model
web6_fahrn_get_agent_skillGet the evolved best_skill.md for an agent + task category
web6_fahrn_evolve_agent_skillRun one SkillOpt epoch — evolve the agent's skill document
web6_generate_imageImage generation via StabilityAI or OpenAI DALL·E
web6_embedGenerate embeddings via OpenAI, Cohere, or HuggingFace
web6_braid_find_graphLook up shared BRAID reasoning graph for a task type
web6_braid_save_graphStore a Mermaid reasoning graph in the BRAID library
web6_braid_record_outcomeFeed solver outcome back into graph quality metadata
web6_memory_get_earth_holonGet/create the planetary Earth holon (top of fractal hierarchy)
web6_memory_get_or_create_holonFind or create a holon at any level in the fractal hierarchy
web6_memory_set_membrane_ruleSet consent-governed upward-propagation rule on a holon
web6_memory_recordRecord a memory item at a holon
web6_memory_propagatePropagate permitted memories up one hop to parent holon
web6_memory_propagate_upPropagate up N hops (or to Earth root)
web6_memory_searchSemantic search over memory items in a holon
web6_memory_external_searchSearch Mem0, Zep, Letta, LangMem, Graphiti, Qdrant, Weaviate external providers
web6_memory_external_addAdd a memory to an external provider (Mem0, Zep, etc.)
web6_memory_external_list_providersList registered external memory providers
web6_orchestrator_registerRegister an external agent/orchestrator endpoint
web6_orchestrator_listList all registered orchestrator adapters
web6_orchestrator_invokeInvoke a registered orchestrator (MCP, A2A, ACP, ANP, LangGraph, OpenAI Agents SDK, Nostr NIP-90, LangChain, AutoGen, CrewAI, SemanticKernel, gRPC, GraphQL, Kafka, AMQP, MQTT, Webhook)
web6_orchestrate_crewaiDispatch a CrewAI task list through WEB6 routing
web6_orchestrate_autogenRoute an AutoGen conversation initiation through WEB6
web6_orchestrate_langgraphExecute a LangGraph node via WEB6, return updated state
web6_list_modelsBrowse the full model catalogue, filter by plan or capability
web6_get_modelFull detail for a single model by ID
web6_list_providersAll 99 providers with tier, endpoints, and status
web6_estimate_costUSD cost estimate before executing a call
web6_get_usageAvatar's daily call count, limit, and monthly spend
web6_get_avatar_contextRich avatar context block — karma, quests, world memberships
web6_list_openserv_modelsList every model in the OpenServ SERV catalog
web6_ml_classify_taskIn-process ML.NET task classification (zero latency)
web6_ml_sentimentIn-process ML.NET sentiment analysis (zero latency)
web6_healthAPI status, version, and UTC timestamp (unauthenticated)

Rate Limits & Headers

Every response includes rate-limit context headers:

HeaderDescription
X-RateLimit-LimitEffective daily call limit for this avatar (plan × karma multiplier)
X-RateLimit-RemainingCalls remaining today
X-RateLimit-ResetUnix timestamp of next quota reset (UTC midnight)
X-RateLimit-PlanCurrent subscription plan
X-Karma-MultiplierKarma multiplier applied to base quota (1.0–10.0)

Quota exceeded returns HTTP 429 with Retry-After seconds until midnight UTC.

All responses use the OASISResult envelope:

{
  "isError": false,
  "message": null,
  "result": { /* endpoint-specific data */ }
}

Webhook Delivery & HMAC Signing

Async endpoints (video generation, batch jobs, fine-tuning) accept a callbackUrl field. When the job completes, WEB6 POSTs a signed WebhookPayload to that URL:

{
  "jobId":          "abc123",
  "jobType":        "video",
  "status":         "completed",
  "result":         { /* job-specific result */ },
  "error":          null,
  "completedAtUtc": "2026-08-23T10:05:22Z"
}

When the WEB6_WEBHOOK_SECRET environment variable is set on the server, every delivery also includes:

HeaderValue
X-WEB6-Signaturesha256=<hex> — HMAC-SHA256 of the raw JSON body, keyed with the shared secret
X-WEB6-EventJob type string, e.g. video, batch, finetune

Verify the signature in your callback endpoint:

# Python verification example
import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)