Build with TrivaNexus
1. Get an API key
Create an account, then create a key in the dashboard. Keys are private to your account and can be revoked at any time.
2. Point your client at the base URL
https://agentic.trivanexus.com/api/v1Send your key as a Bearer token (Authorization: Bearer …) or in an x-api-key header. Coding agents such as Cline and Continue work by choosing their “OpenAI compatible” provider and entering this base URL and your key.
OpenAI SDK (Node)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://agentic.trivanexus.com/api/v1",
apiKey: process.env.TRIVA_API_KEY,
});
const res = await client.chat.completions.create({
model: "adaptive",
messages: [{ role: "user", content: "Hello" }],
stream: true,
});
for await (const chunk of res) {
process.stdout.write(chunk.choices[0]?.delta?.content || "");
}OpenAI SDK (Python)
from openai import OpenAI
import os
client = OpenAI(
base_url="https://agentic.trivanexus.com/api/v1",
api_key=os.environ["TRIVA_API_KEY"],
)
res = client.chat.completions.create(
model="adaptive",
messages=[{"role": "user", "content": "Hello"}],
)
print(res.choices[0].message.content)Adaptive mode
Request model: "adaptive" and the gateway scores each request's complexity and routes it to a matching tier — fast models for simple turns, frontier models for architecture, debugging and security work. A conversation stays on one model so prompt caching keeps working, and a failed call escalates to the next tier. smart-routing and cline are accepted as aliases.
Adaptive requests are billed at the per-token price of the model that serves them. Each response tells you where it went:
X-Triva-Routed-Model— the model that served the requestX-Triva-Tier/X-Triva-Complexity— the tier (1–3) and complexity score (1–5)X-Triva-Sticky— whether the conversation's earlier model was reused
Reusable skills
Add triva.skills to attach up to three skill slugs explicitly, or set triva.auto_skills: true to select relevant skills from task hints. Applied skill versions are returned in applied_skills and the X-Triva-Skills response header. A skill that requires tools only runs when those tools are advertised by the request.
MCP connections
Select organization-managed MCP servers with triva.mcp_connections. The gateway discovers permitted tools, exposes namespaced functions to the model and executes returned calls. MCP execution currently requires stream: false. Connections require explicit approval by default through X-Triva-Approve-MCP: true, and applied connections are reported in the X-Triva-MCP response header.
Endpoints
POST /v1/chat/completionsOpenAI-compatible chat completions with streaming and tool calling. Use model "adaptive" or any model id.
GET /v1/modelsList all chat models in the catalog, including models discovered from OpenRouter and Kimi.
GET /v1/user/modelsModels your organization allows, its default model, and whether adaptive mode is enabled.
GET /v1/usageToken and cost usage for your key, plus today's allowance.
GET /v1/skillsList enabled reusable skills, task hints, versions and required tools.
GET /v1/memoriesList or full-text search your long-term memories in a namespace; POST to save one. Opt requests in with triva.memory.
PATCH /v1/memories/{id}Update or (with DELETE) remove one of your memories.
GET /v1/tracesYour recent request traces; filter with run_id and status. Every chat response returns its X-Triva-Trace-Id.
GET /v1/traces/{id}One trace with its spans: routing, model calls, provider attempts and tool calls. Metadata only, never prompt text.
GET /v1/mcp/tools?connections=slugDiscover permitted tools from selected Streamable HTTP MCP servers.
POST /v1/agent/executeOne step of the Triva GeoAgent QGIS plugin: the agent's thoughts, plan, message and at most one PyQGIS script, as SSE or JSON events.
GET /v1/healthLiveness check; with an API key it also reports whether the key is valid, its plan, and the GeoAgent trial balance.
POST /v1/tools/executeRun a gateway file tool (read_file, write_file, edit_file, list_dir) in the sandboxed workspace.
Errors
Errors come back as JSON { "error": "…" }. The gateway never substitutes a placeholder reply for a failed request.
| 400 | Unknown model id, or adaptive mode is turned off for your organization. |
| 401 | Missing or invalid API key. |
| 429 | Your key's daily token budget is used up. |
| 502 | Providers were tried and all failed. The message names each provider and its HTTP status. |
| 503 | No provider is configured to serve this model. |
Hugging Face free-tier models
Some models are served through Hugging Face Inference Providers on its free tier. Any Hugging Face model can be requested with the huggingface/ prefix. If you self-host TrivaNexus, set HF_TOKEN to enable them.
// Verified free-tier model from Hugging Face Inference Providers
const res = await client.chat.completions.create({
model: "huggingface/meta-llama/Llama-3.1-8B-Instruct",
messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);Ready to build?
Create an account, grab a key and send your first request in minutes.
Create an account