Appearance
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.
| Method | Endpoint |
|---|---|
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()?;