Evigauge REST API Reference

Authorization: Bearer dr_live_xxxxxxxxxxxxxxxxxxxx

x-opexia-api-key: opx_live_xxxxxxxxxxxxxxxxxxxx

Authorization: Bearer <jwt>
x-opexia-workspace-id: 3f2b1c8e-9a4d-4f11-b7c2-1e5a8d3f6b90

{
  "data": ...,
  "meta": { "request_id": "…", "schema_version": "1.0", "scorer_version": "…" }
}

GET .../traces?page_size=50
→ { "data": [...], "next_cursor": "eyJ0cyI6...", "meta": {...} }

GET .../traces?page_size=50&cursor=eyJ0cyI6...
→ { "data": [...], "next_cursor": null, "meta": {...} }     # null = last page

{
  "detail": [
    { "loc": ["body", "hours"], "msg": "field required", "type": "value_error.missing" }
  ]
}

{ "detail": "workspace not found" }

# Python — nothing required for REST; httpx is recommended
pip install httpx

# TypeScript — fetch is built in on Node 18+, no dependency needed

import httpx

BASE    = "https://api.opexia.dev"
API_KEY = "opx_live_xxxxxxxxxxxxxxxxxxxx"
ORG, WS = "acme", "prod"

r = httpx.get(
    f"{BASE}/v1/observ/orgs/{ORG}/workspaces/{WS}/traces",
    headers={"x-opexia-api-key": API_KEY},
    params={"page_size": 10},
    timeout=30,
)
r.raise_for_status()
# Payload is under "data", not "items".
for t in r.json()["data"]:
    print(t["trace_id"], t.get("grade"), t.get("cost_usd_total"))

const BASE = "https://api.opexia.dev";
const API_KEY = process.env.OPEXIA_API_KEY!;
const ORG = "acme", WS = "prod";

const res = await fetch(
  `${BASE}/v1/observ/orgs/${ORG}/workspaces/${WS}/traces?page_size=10`,
  { headers: { "x-opexia-api-key": API_KEY } },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { data } = await res.json();   // payload is under "data", not "items"
for (const t of data) console.log(t.trace_id, t.grade, t.cost_usd_total);

# evigauge.py
import os, time, random, httpx

class Evigauge:
    def __init__(self, api_key=None, org=None, ws=None,
                 base="https://api.opexia.dev", timeout=30.0):
        self.key  = api_key or os.environ["OPEXIA_API_KEY"]
        self.org  = org or os.environ.get("OPEXIA_ORG")
        self.ws   = ws  or os.environ.get("OPEXIA_WORKSPACE")
        self.base = base.rstrip("/")
        self._c   = httpx.Client(timeout=timeout,
                                 headers={"x-opexia-api-key": self.key})

    def request(self, method, path, *, retries=3, **kw):
        """Call any endpoint. `path` may contain {org}/{ws} placeholders."""
        url = self.base + path.format(org=self.org, ws=self.ws)
        for attempt in range(retries + 1):
            r = self._c.request(method, url, **kw)
            # 429 and 5xx are transient — back off and retry.
            if r.status_code in (429, 502, 503, 504) and attempt < retries:
                time.sleep((2 ** attempt) + random.random())
                continue
            if r.status_code >= 400:
                raise httpx.HTTPStatusError(
                    f"{r.status_code} {r.text}", request=r.request, response=r)
            return r.json() if r.content else None
        raise RuntimeError("unreachable")

    def get(self, p, **kw):    return self.request("GET", p, **kw)
    def post(self, p, **kw):   return self.request("POST", p, **kw)
    def put(self, p, **kw):    return self.request("PUT", p, **kw)
    def patch(self, p, **kw):  return self.request("PATCH", p, **kw)
    def delete(self, p, **kw): return self.request("DELETE", p, **kw)

    def paginate(self, path, **params):
        """Yield every row across all pages of a cursor-paginated endpoint."""
        cursor = None
        while True:
            extra = {"cursor": cursor} if cursor else {}
            page = self.get(path, params={**params, **extra})
            # Payload is under "data", not "items".
            yield from (page.get("data") or [])
            # /traces puts next_cursor at the top level; /audit-log nests it in meta.
            cursor = page.get("next_cursor") or (page.get("meta") or {}).get("next_cursor")
            if not cursor:
                return

evigauge = Evigauge()

// evigauge.ts
export interface EvigaugeOptions {
  apiKey?: string; org?: string; ws?: string;
  base?: string; timeoutMs?: number;
}

export class Evigauge {
  private key: string; private org: string; private ws: string;
  private base: string; private timeoutMs: number;

  constructor(o: EvigaugeOptions = {}) {
    this.key  = o.apiKey ?? process.env.OPEXIA_API_KEY!;
    this.org  = o.org    ?? process.env.OPEXIA_ORG!;
    this.ws   = o.ws     ?? process.env.OPEXIA_WORKSPACE!;
    this.base = (o.base ?? "https://api.opexia.dev").replace(/\/$/, "");
    this.timeoutMs = o.timeoutMs ?? 30_000;
  }

  async request<T = any>(
    method: string, path: string,
    opts: { query?: Record<string, any>; body?: unknown; retries?: number } = {},
  ): Promise<T> {
    const { query, body, retries = 3 } = opts;
    const resolved = path.replace("{org}", this.org).replace("{ws}", this.ws);
    const url = new URL(this.base + resolved);
    for (const [k, v] of Object.entries(query ?? {}))
      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));

    for (let attempt = 0; ; attempt++) {
      const res = await fetch(url, {
        method,
        signal: AbortSignal.timeout(this.timeoutMs),
        headers: {
          "x-opexia-api-key": this.key,
          ...(body ? { "content-type": "application/json" } : {}),
        },
        ...(body ? { body: JSON.stringify(body) } : {}),
      });
      // 429 and 5xx are transient — back off and retry.
      if ([429, 502, 503, 504].includes(res.status) && attempt < retries) {
        await new Promise(r =>
          setTimeout(r, 2 ** attempt * 1000 + Math.random() * 1000));
        continue;
      }
      if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
      return res.status === 204 ? (undefined as T) : await res.json();
    }
  }

  get   = <T = any>(p: string, query?: Record<string, any>) => this.request<T>("GET", p, { query });
  post  = <T = any>(p: string, body?: unknown, query?: Record<string, any>) => this.request<T>("POST", p, { body, query });
  put   = <T = any>(p: string, body?: unknown) => this.request<T>("PUT", p, { body });
  patch = <T = any>(p: string, body?: unknown) => this.request<T>("PATCH", p, { body });
  del   = <T = any>(p: string) => this.request<T>("DELETE", p);

  /** Async-iterate every row across all pages of a cursor-paginated endpoint. */
  async *paginate<T = any>(path: string, query: Record<string, any> = {}) {
    let cursor: string | null = null;
    do {
      const page = await this.get(path, { ...query, ...(cursor ? { cursor } : {}) });
      // Payload is under "data", not "items".
      yield* ((page.data ?? []) as T[]);
      // /traces puts next_cursor at the top level; /audit-log nests it in meta.
      cursor = page.next_cursor ?? page.meta?.next_cursor ?? null;
    } while (cursor);
  }
}

export const evigauge = new Evigauge();

export OPEXIA_API_KEY="opx_live_xxxxxxxxxxxxxxxxxxxx"
export OPEXIA_ORG="acme"
export OPEXIA_WORKSPACE="prod"