Documentation

Build with TrivaNexus

One OpenAI-compatible API for many models. Use the OpenAI SDK — or any OpenAI-compatible agent — you already know.

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/v1

Send 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)

typescript
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)

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 request
  • X-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/completions

OpenAI-compatible chat completions with streaming and tool calling. Use model "adaptive" or any model id.

GET /v1/models

List all chat models in the catalog, including models discovered from OpenRouter and Kimi.

GET /v1/user/models

Models your organization allows, its default model, and whether adaptive mode is enabled.

GET /v1/usage

Token and cost usage for your key, plus today's allowance.

GET /v1/skills

List enabled reusable skills, task hints, versions and required tools.

GET /v1/memories

List 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/traces

Your 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=slug

Discover permitted tools from selected Streamable HTTP MCP servers.

POST /v1/agent/execute

One 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/health

Liveness check; with an API key it also reports whether the key is valid, its plan, and the GeoAgent trial balance.

POST /v1/tools/execute

Run 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.

400Unknown model id, or adaptive mode is turned off for your organization.
401Missing or invalid API key.
429Your key's daily token budget is used up.
502Providers were tried and all failed. The message names each provider and its HTTP status.
503No 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.

typescript
// 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