Client

The client handles authentication, request building, response parsing, and SSE streaming. Both the Go and TypeScript SDKs expose the same flat method surface — one method per /api/sdk/* endpoint.

Creating a client

Go

import tavora "github.com/tavora-ai/tavora-sdk-go"

client := tavora.NewClient(
    "https://api.tavora.ai", // or http://localhost:8080 in dev
    "tvr_your_api_key",      // app-scoped API key
)

TypeScript

import { Client } from '@tavora/sdk';

const client = new Client(
  'https://api.tavora.ai',   // or http://localhost:8080 in dev
  'tvr_your_api_key',        // app-scoped API key
);

The API key determines which app all operations are scoped to. One key, one app — multi-app deployments mint one key per app and create a separate client per app.

Authentication

Every request sends X-API-Key: tvr_... to /api/sdk/*. Keys are app-scoped — one key, one app. Mint one in the admin web UI (covered in the platform’s internal docs) and either pass it to the client directly or store it via tavora login so the CLI picks it up too.

To work with multiple apps from the same process, create separate clients:

Go

prodClient    := tavora.NewClient(baseURL, "tvr_prod_key")
stagingClient := tavora.NewClient(baseURL, "tvr_staging_key")

TypeScript

const prodClient    = new Client(baseUrl, 'tvr_prod_key');
const stagingClient = new Client(baseUrl, 'tvr_staging_key');

Error handling

Failures return a typed error with code, message, and a details map carrying any structured fields from the server. Two recovery helpers ship out of the box:

Go

doc, err := client.GetDocument(ctx, id)
if err != nil {
    if conflict, ok := tavora.AsVersionConflict(err); ok {
        // 409: re-read, merge, retry with conflict.CurrentVersion
    }
    var apiErr *tavora.APIError
    if errors.As(err, &apiErr) {
        log.Printf("[%d] %s — code=%s details=%v",
            apiErr.StatusCode, apiErr.Message, apiErr.Code, apiErr.Details)
    }
}

TypeScript

import {
  TavoraAPIError,
  asVersionConflict,
  isNotFound,
  isUnauthorized,
} from '@tavora/sdk';

try {
  await client.getDocument(id);
} catch (err) {
  const conflict = asVersionConflict(err);
  if (conflict) {
    // retry with conflict.currentVersion
  } else if (isNotFound(err)) {
    // 404
  } else if (isUnauthorized(err)) {
    // 401 — re-mint API key (browser path) or check env (backend path)
  } else if (err instanceof TavoraAPIError) {
    console.error(err.status, err.code, err.apiMessage, err.details);
  }
}

Network errors (DNS, timeout, TLS) come through as error / exception values from the underlying transport — they don’t carry an HTTP status.

Base URL

In development the server typically runs at http://localhost:8080. In production, point at your deployed Tavora instance — https://api.tavora.ai for the hosted platform, or your self-hosted hostname.

What you’d configure next

• MCP servers — declare your domain API in agent.jsonc → mcp so the agent can call your tools.
• Browser-based chat — session-token exchange for browser SDK consumers.
• tavora CLI — author agents code-first with init / dev / deploy.