Docs Use Eco

API quickstart

Connect with your Orbio key using curl or an OpenAI-compatible SDK.

On this page

Learn how to authenticate, send your first chat request, and read its route.

Base URL and key#

Production API: https://api.orbioeco.sh. Endpoint paths start with /v1. For an OpenAI-compatible SDK, use https://api.orbioeco.sh/v1 as the base URL.

Send your own Orbio key as Authorization: Bearer sk-orbio-…. Eco does not issue keys. Orbio validates the key when an upstream call runs.

For local development, replace the origin with http://localhost:8787 (or your configured port). See Installation & usage.

Main endpoints#

Method	Path	Key required?	Purpose
GET	`/v1/eco/health`	No	Check that the API is responding.
GET	`/v1/eco/catalog`	No	Read active catalog models, seed prices, and capabilities.
GET	`/v1/models`	No	List model ids and the four auto aliases.
POST	`/v1/eco/route/preview`	Yes	Inspect a decision without generating the requested answer.
POST	`/v1/chat/completions`	Yes	Route and run a chat completion, with optional streaming.

Preview uses the same model and messages fields as chat and returns { decision: ... }. It can make a paid classifier call. Preview and chat route independently. See How it works.

First request with curl#

Replace the placeholder with your Orbio key. This request spends credits; -i also prints route headers.

eco@docs bash

export ORBIO_KEY='sk-orbio-…'
curl --fail-with-body -i https://api.orbioeco.sh/v1/chat/completions \
  -H "Authorization: Bearer $ORBIO_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"auto/balanced","messages":[{"role":"user","content":"Explain HTTP caching in two sentences."}]}'

Developers: JavaScript SDK#

The official JavaScript SDK can call Eco's OpenAI-compatible Chat Completions endpoint. Install it in your own application's directory:

eco@docs bash

pnpm add openai
export OPENAI_BASE_URL=https://api.orbioeco.sh/v1
export OPENAI_API_KEY='sk-orbio-…'

Save this as example.mjs, then run node example.mjs:

eco@docs js

import OpenAI from "openai";

const eco = new OpenAI({
  baseURL: process.env.OPENAI_BASE_URL,
  apiKey: process.env.OPENAI_API_KEY,
});
const reply = await eco.chat.completions.create({
  model: "auto/balanced",
  messages: [
    { role: "user", content: "Explain HTTP caching in two sentences." },
  ],
});
console.log(reply.choices[0].message.content);

Use your Orbio key, not an OpenAI key. Use chat.completions.create; Eco does not implement the Responses API. To stream a reply, add stream: true and consume the returned stream. Raw HTTP streaming uses server-sent events.

Read the route#

Response header	Meaning
`x-eco-model-selected`	Model that Eco selected or passed through.
`x-eco-tier`	`cheap`, `balanced`, `best`, or `pass-through`.
`x-eco-route-reason`	Short explanation of the choice.
`x-eco-classifier-used`	`1` if the classifier was attempted; otherwise `0`.
`x-eco-est-cost-per-1m`	Seed output price in USD per one million tokens. Absent when unknown.

Chat headers describe the actual route, even if a preview differed. They are available when a stream starts. Early validation, authentication, and rate-limit errors do not include route headers.

Catalog prices are seed snapshots. The output estimate excludes input tokens and classifier costs. Savings illustrations are not guarantees.

Common errors#

A 400 usually means the request is malformed or no model supports its requirements. A 401 means Bearer auth is missing or Orbio rejected the key. A 429 means a rate limit was reached; for Eco's limit, wait for the Retry-After seconds.

Eco errors use { "error": { "message": "...", "type": "...", "code": "eco_..." } }. Upstream errors are relayed from Orbio. Only the five endpoints above are supported.

Next: Privacy & keys or FAQ.