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.

1
import { TraceDBClient } from "@tracedb/sdk";
2
3
const client = new TraceDBClient({
4
  baseUrl: process.env.TRACEDB_URL!,
5
  token: process.env.TRACEDB_TOKEN,
6
  maxRetries: 0,
7
});

1
import os
2
from tracedb import TraceDB
3
4
db = TraceDB(
5
    base_url=os.environ["TRACEDB_URL"],
6
    token=os.environ["TRACEDB_TOKEN"],
7
    max_retries=0,
8
)

1
use tracedb_sdk::prelude::*;
2
3
let config = ClientConfig {
4
    base_url: std::env::var("TRACEDB_URL")?,
5
    token: Some(std::env::var("TRACEDB_TOKEN")?),
6
    max_retries: 0,
7
    ..Default::default()
8
};
9
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

1
# Cargo.toml
2
[dependencies]
3
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

• Use API authentication for token and routing rules.
• Use TraceQL and Native and Bounded GraphQL for query examples.
• Use Idempotency and Retries before retrying writes or polymorphic operations.