Skip to content

Rust SDK ​

First release

The API currently serves chat, web search and page reading. SDK methods for other features (embeddings, crawl, research, sandbox, browser, files) return a 404 error until those features are switched on.

toml
[dependencies]
usefully = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
rust
use usefully::{ChatMessage, ChatRequest, Client};

#[tokio::main]
async fn main() -> Result<(), usefully::Error> {
    let client = Client::from_env()?; // reads USEFULLY_API_KEY
    let reply = client
        .chat(ChatRequest::new(
            "anthropic/claude-sonnet-5-5",
            vec![ChatMessage::user("Hello")],
        ))
        .await?;
    println!("{}", reply.text());
    Ok(())
}

The chat and embedding types are the ones the gateway itself uses (usefully-types), so every field the API accepts is available. Unknown fields round-trip through extra.

MethodEndpoint
chat(req) / chat_with(req, &options)POST /v1/chat/completions
chat_stream(req) → ChatStream (futures::Stream of chunks)POST /v1/chat/completions with stream: true
embeddings(&req)POST /v1/embeddings
rerank(&req)POST /v1/rerank
search(&SearchRequest::new("…"))POST /v1/search
extract(&ExtractRequest::new(["https://…"]))POST /v1/extract
crawl(&CrawlRequest::new("https://…"))POST /v1/crawl
research(&req) / research_and_wait(&req, timeout)POST /v1/research
job(id), job_results(id, after, limit), cancel_job(id), wait_for_job(id, poll, timeout)/v1/jobs…
sandbox_run(&SandboxRunRequest::new("print(1)"))POST /v1/sandbox/run
create_browser(&req), browser(id), release_browser(id)/v1/browser/sessions…
models()GET /v1/models
request::<T>(method, path, body, &options)Any other endpoint

Errors and retries ​

Every method returns Result<_, usefully::Error>. Error::Api { status, detail } holds the unified error body. err.kind() gives the ErrorType, and detail.code gives the exact reason. Connection errors, 429 and 5xx are retried twice with backoff, honouring Retry-After. You can change the count with Client::builder().max_retries(n). A stream is never retried once it has started.

Configuration ​

rust
let client = Client::builder()
    .api_key("uf_live_…")                    // default: USEFULLY_API_KEY
    .base_url("https://api.usefully.info/v1")  // default: USEFULLY_BASE_URL or this
    .timeout(std::time::Duration::from_secs(120))
    .header("Usefully-Cache", "3600")        // sent on every request
    .build()?;