Skip to content
Olivares AI docs

Use the client SDKs (Go, Java, Python, TypeScript)

The control plane ships four first-party client SDKs for its published REST contract (/v1), generated from the same OpenAPI document the engine serves and the API reference renders:

SDKPackageRuntime needs
Gogithub.com/olivaresai/olivares/clients/go (package olivares)stdlib only
Javaai.olivares:olivares-client (package ai.olivares.client)Java ≥ 17, JDK java.net.http only
Pythonolivares-client (import olivares_client)Python ≥ 3.10, stdlib only
TypeScript@olivaresai/clientglobal fetch (Node ≥ 20, Deno, browsers)

All four share one design. A hand-written core implements the contractual behaviour — opaque bearer tokens (olvs_ session / olvk_ API key), the X-Olivares-Tenant header, the API’s single error envelope, cursor pagination (items/cursor/has_more), retries that honour Retry-After for rate-limited calls (429 always; 503 only for idempotent GETs), and the stability policy’s deprecation headers surfaced once per endpoint. On top sits a generated method per published operation, named after the route (GET /v1/agents → GetV1Agents / get_v1_agents / getV1Agents), with request/response bodies as generic JSON — the published contract deliberately keeps bodies opaque.

Go

Section titled “Go”
import olivares "github.com/olivaresai/olivares/clients/go"


c, err := olivares.New("https://olivares.example:8443", os.Getenv("OLIVARES_API_TOKEN"),
    olivares.WithTenant("9be0…"))
if err != nil { … }


info, err := c.GetV1ServerInfo(ctx)


for agent, err := range c.ListPages(ctx, "/v1/agents", olivares.Query("limit", "100")) {
    if err != nil { … }
    fmt.Println(agent["id"])
}

Errors are *olivares.APIError (match with errors.As); Code carries the contract’s stable error codes (not_found, forbidden, rate_limited, …). Deprecation signals arrive once per endpoint as an slog warning, or your own WithDeprecationHandler callback.

Java

Section titled “Java”
import ai.olivares.client.Client;
import ai.olivares.client.ClientOptions;
import ai.olivares.client.OlivaresApiException;
import ai.olivares.client.RequestOptions;


Client c = new Client(ClientOptions.builder()
    .endpoint("https://olivares.example:8443")
    .token(System.getenv("OLIVARES_API_TOKEN"))
    .tenant("9be0…")
    .build());


var info = c.getV1ServerInfo();


for (var agent : c.paginate("/v1/agents",
        RequestOptions.builder().query("limit", "100").build())) {
    System.out.println(agent.get("id"));
}

Errors throw OlivaresApiException with getStatus(), getCode(), getApiMessage() and getRequestId(). Deprecation signals arrive once per endpoint via the onDeprecation callback. The core is zero-dependency — just the JDK’s java.net.http and a hand-rolled JSON codec.

Python

Section titled “Python”
from olivares_client import Client, APIError


c = Client("https://olivares.example:8443", token="olvk_…", tenant="9be0…")


info = c.get_v1_server_info()
for agent in c.paginate("/v1/agents", limit="100"):
    print(agent["id"])

Errors raise APIError with .status, .code, .message, .request_id. Deprecated endpoints emit one DeprecationWarning per endpoint (or your on_deprecation= callback). For the engine’s out-of-the-box self-signed TLS, pass verify=False in labs — pin a real CA in production.

TypeScript

Section titled “TypeScript”
import { Client, APIError } from "@olivaresai/client";


const c = new Client({ endpoint: "https://olivares.example:8443", token: "olvk_…" });


const info = await c.getV1ServerInfo();
for await (const agent of c.paginate("/v1/agents", { query: { limit: "100" } })) {
  console.log(agent.id);
}

Errors are APIError instances; deprecation signals arrive once per endpoint via console.warn or your onDeprecation callback.

Versioning and regeneration

Section titled “Versioning and regeneration”

Each SDK exports API_VERSION (the API contract major it was generated from) and SPEC_HASH (the SHA-256 of the exact OpenAPI snapshot) — APIVersion and SpecHash in Go. The operation layers are regenerated by task sdk:generate and drift-checked by task sdk:check, which runs in the pre-push gate and in CI — a contract change cannot silently diverge from the shipped clients. The compatibility commitment for everything the SDKs touch is the API stability policy.

Section titled “Related”