Skip to navigation
Start

Quickstarts

Use these examples to configure a client for local runtime development or invite-only Hosted Alpha access. v0.1.x SDK package names are staged for private alpha distribution until v1; use install snippets only when your invite or package credentials include access.

Environment

For a local runtime:

export TRACEDB_URL=http://127.0.0.1:8090
export TRACEDB_TOKEN=dev-token

For Hosted Alpha, use the hosted API URL and a scoped API key issued by the control plane:

export TRACEDB_URL=https://api.trace-db.com
export TRACEDB_TOKEN=<scoped-api-key>
export TRACEDB_DATABASE_ID=<database-id>
export TRACEDB_BRANCH_ID=<branch-id>

Do not put hosted API keys in source control, docs, ledgers, issue comments, or chat output.

These environment variables are a shell convention used by curl examples and any SDK helper that your private-alpha package documents. Follow the generated SDK’s documented helpers when available, and fall back to explicit constructor or config fields from the OpenAPI operation shape. Do not assume fromEnv / from_env helpers exist unless the owning SDK README for your installed package shows them for that version.

import { TraceDBClient } from "@tracedb/sdk";
const client = new TraceDBClient({
  baseUrl: process.env.TRACEDB_URL!,
  token: process.env.TRACEDB_TOKEN,
  maxRetries: 0,
});
import os
from tracedb import TraceDB
db = TraceDB(
    base_url=os.environ["TRACEDB_URL"],
    token=os.environ["TRACEDB_TOKEN"],
    max_retries=0,
)
use tracedb_sdk::prelude::*;
let config = ClientConfig {
    base_url: std::env::var("TRACEDB_URL")?,
    token: Some(std::env::var("TRACEDB_TOKEN")?),
    max_retries: 0,
    ..Default::default()
};
let client = ApiClient::new(config)?;

SDK Package Access

If you have private alpha package access, pin the staged v0.1.1 SDKs:

npm install @tracedb/sdk@0.1.1
pip install tracedb==0.1.1
# Cargo.toml
[dependencies]
tracedb-sdk = "0.1.1"

Go SDK support is reserved/candidate and is not a v0.1.1 private alpha install surface yet.

HTTP Smoke

The API reference is the source of truth for exact route shapes. A minimal HTTP readiness check looks like:

curl -fsS "$TRACEDB_URL/v1/ready" \
  -H "Authorization: Bearer $TRACEDB_TOKEN"

For hosted calls, use the SDK or gateway-supported routing metadata so the request is bound to the authorized tenant, database, and branch. Do not send x-tracedb-* actor headers as a way to impersonate routing state; the hosted gateway strips client-supplied actor headers and injects trusted metadata from verified claims.

Next Steps