HTTP client | Brain Docs

Construct a client

There are two constructors. Note the argument order on new:

use brain_db_sdk::BrainHttpClient;

// base_url FIRST, then the API key.
let client = BrainHttpClient::new("https://api.arc-labs.ai", "my-api-key");

// Or point at the self-host default (http://127.0.0.1:8080):
let local = BrainHttpClient::localhost("my-api-key");

BrainHttpClient::new(base_url, api_key) takes the base URL first and the API key second — the reverse of what you might expect. Getting them backwards sends your key as the URL and your URL as the credential. Use localhost(api_key) when you only need the single argument.

The client is Clone and cheap to share; the underlying reqwest::Client pools connections internally.

Builder options

Both constructors start with a 30-second request timeout and the default retry policy. Override either with a chained builder:

use std::time::Duration;
use brain_db_sdk::{BrainHttpClient, HttpRetryPolicy};

let client = BrainHttpClient::new("https://api.arc-labs.ai", "my-api-key")
    .with_timeout(Duration::from_secs(10))
    .with_retry_policy(HttpRetryPolicy::none()); // disable retry

ParameterTypeRequired

with_timeoutDurationoptional

Per-request timeout. Default is 30 seconds. A timeout surfaces as a transport BrainHttpError (status: 0), never a panic.

with_retry_policyHttpRetryPolicyoptional

Retry schedule applied to idempotent verbs. Default is 3 attempts with exponential backoff (100 ms base, 2 s cap). Pass HttpRetryPolicy::none() to disable.

Authentication

The client sends the API key as an HTTP bearer token on every request:

Authorization: Bearer <api_key>

There is no anonymous mode — the key is the whole identity, and the server resolves the (namespace, agent, permissions) tuple from it. Call whoami() to see what the server resolved.

Supported verbs

The HTTP client is a strict subset of the full surface. Every method is async and returns Result<_, BrainHttpError>:

Method	Route	Input	Result
`encode`	`POST /v1/memories`	`EncodeInput`	`EncodeResult`
`recall`	`POST /v1/recall`	`RecallInput`	`RecallResult`
`forget`	`DELETE /v1/memories`	`ForgetInput`	`ForgetResult`
`link`	`POST /v1/links`	`LinkInput`	`LinkResult`
`unlink`	`DELETE /v1/links`	`UnlinkInput`	`UnlinkResult`
`plan`	`POST /v1/plan`	`PlanInput`	`PlanResult`
`reason`	`POST /v1/reason`	`ReasonInput`	`ReasonResult`
`whoami`	`GET /v1/whoami`	—	`Whoami`
`capabilities`	`GET /v1/capabilities`	—	`Capabilities`

The input and result types live under brain_db_sdk::http. Optional request fields skip when None, so ..Default::default() gives you a minimal body:

use brain_db_sdk::http::EncodeInput;

let out = client
    .encode(&EncodeInput {
        text: "Ada prefers dark mode.".to_string(),
        ..Default::default()
    })
    .await?;

Only idempotent verbs — encode (stable server-side request id), whoami, and capabilities — are retried. recall, forget, link, unlink, plan, and reason run exactly once. Retryable failures are HTTP 503 and transport/timeout errors; every 4xx is a terminal verdict.

Identity and capabilities

Two GETs let you introspect the connection:

let who = client.whoami().await?;
println!("namespace={:?} agent={}", who.namespace, who.agent_id);
println!("can_encode={} can_forget={}", who.permissions.can_encode, who.permissions.can_forget);

let caps = client.capabilities().await?;
println!("rerank loaded: {}, vector dim: {}", caps.rerank, caps.vector_dim);