Skip to content

API reference ​

One API key for LLMs, embeddings, search, retrieval and agent tools. Base URL: https://api.usefully.info/v1.

Authenticate with Authorization: Bearer <key> (see Authentication). Errors use the standard error shape.

Generated from openapi.json.

System ​

Health and readiness.

GET /healthz ​

Liveness: the process is up and serving HTTP.

No API key needed.

StatusDescriptionBody
200string (text/plain)

GET /readyz ​

Readiness: dependencies are reachable, so the instance can take traffic.

No API key needed.

StatusDescriptionBody
200Readiness (application/json)
503Readiness (application/json)

GET /v1/status ​

Current service status. Public, cached by clients for ~30 s.

No API key needed.

StatusDescriptionBody
200Status (application/json)

Billing ​

Credits, purchases and balance alerts.

GET /v1/billing ​

Balance and billing settings for the calling key's organization.

Requires an API key.

StatusDescriptionBody
200BillingOverview (application/json)

POST /v1/billing/checkout ​

Starts a credit purchase. Credits are added when the payment is confirmed.

Requires an API key.

Request body: CheckoutRequest

StatusDescriptionBody
200CheckoutResponse (application/json)

PUT /v1/billing/settings ​

Updates the low-balance alert setting.

Requires an API key.

Request body: SettingsUpdate

StatusDescriptionBody
200BillingOverview (application/json)

GET /v1/currencies ​

No API key needed.

StatusDescriptionBody
200CurrencyList (application/json)

Tools ​

Code sandboxes and headless browsers for agents, billed by time.

GET /v1/browser/sessions ​

Requires an API key.

StatusDescriptionBody
200SessionList (application/json)

POST /v1/browser/sessions ​

Starts a browser. Connect with Playwright (chromium.connectOverCDP(connect_url)) or Puppeteer (puppeteer.connect({browserWSEndpoint: connect_url})).

Requires an API key.

Request body: CreateSession

StatusDescriptionBody
201SessionView (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)

GET /v1/browser/sessions/{id} ​

Requires an API key.

StatusDescriptionBody
200SessionView (application/json)
404ErrorBody (application/json)

DELETE /v1/browser/sessions/{id} ​

Ends a session and bills the minutes used. Ending one that already ended returns it unchanged.

Requires an API key.

StatusDescriptionBody
200SessionView (application/json)
404ErrorBody (application/json)

POST /v1/sandbox/run ​

Runs code in a fresh sandbox and returns stdout, stderr, rich results and any error. Billed per second of sandbox time.

Requires an API key.

Request body: RunRequest

StatusDescriptionBody
200RunResponse (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)

Chat ​

LLM chat (OpenAI-compatible and native Anthropic).

POST /v1/chat/completions ​

Creates a chat completion (OpenAI-compatible). Set stream: true for Server-Sent Events.

Requires an API key.

Request body: ChatRequest

StatusDescriptionBody
200A completion; with stream: true, a text/event-stream of data: <ChatChunk> events ending with data: [DONE]ChatResponse (application/json); ChatChunk (text/event-stream)
400ErrorBody (application/json)
401ErrorBody (application/json)
402Insufficient creditsErrorBody (application/json)
404ErrorBody (application/json)
429ErrorBody (application/json)
502ErrorBody (application/json)
503ErrorBody (application/json)

POST /v1/messages ​

Native Anthropic Messages API for Claude models. The body is forwarded as-is (only model is rewritten), so Anthropic SDKs work unchanged.

Requires an API key.

Request body: object

StatusDescriptionBody
200An Anthropic Messages API response or SSE streamobject (application/json)
400ErrorBody (application/json)
401ErrorBody (application/json)

GET /v1/models ​

Lists available models. Public: no API key needed.

No API key needed.

StatusDescriptionBody
200ModelList (application/json)

Web search and page extraction, billed per query or page.

POST /v1/crawl ​

Starts crawling a website. Returns a job to poll; pages are billed as they're extracted.

Requires an API key.

Request body: CrawlRequest

StatusDescriptionBody
202JobView (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)

POST /v1/extract ​

Extracts the main content of web pages as Markdown. Billed per page.

Requires an API key.

Request body: ExtractRequest

StatusDescriptionBody
200Per-URL results; failed pages aren't billedExtractResponse (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)
429ErrorBody (application/json)

GET /v1/jobs ​

Recent jobs, newest first.

Requires an API key.

StatusDescriptionBody
200JobList (application/json)

GET /v1/jobs/{id} ​

A job's status and progress.

Requires an API key.

StatusDescriptionBody
200JobView (application/json)
404ErrorBody (application/json)

POST /v1/jobs/{id}/cancel ​

Cancels a job. Pages already extracted stay billed and available.

Requires an API key.

StatusDescriptionBody
200JobView (application/json)
404ErrorBody (application/json)

GET /v1/jobs/{id}/results ​

A page of a job's results (available while it runs).

Requires an API key.

StatusDescriptionBody
200JobResults (application/json)
404ErrorBody (application/json)

POST /v1/research ​

Starts a research job. Poll GET /v1/jobs/{id}; progress events and the final report arrive in GET /v1/jobs/{id}/results, and the report and sources are in the job's summary.

Requires an API key.

Request body: ResearchRequest

StatusDescriptionBody
202JobView (application/json)
400ErrorBody (application/json)

POST /v1/search ​

Searches the web. Billed per query.

Requires an API key.

Request body: SearchRequest

StatusDescriptionBody
200SearchResponse (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)
429ErrorBody (application/json)
502ErrorBody (application/json)

Embeddings ​

Text embeddings (OpenAI-compatible) and reranking.

POST /v1/embeddings ​

Creates embeddings for one or more texts.

Requires an API key.

Request body: EmbeddingRequest

StatusDescriptionBody
200EmbeddingResponse (application/json)
400ErrorBody (application/json)
401ErrorBody (application/json)
402Insufficient creditsErrorBody (application/json)
404ErrorBody (application/json)
429ErrorBody (application/json)

POST /v1/rerank ​

Orders documents by relevance to the query.

Requires an API key.

Request body: RerankRequest

StatusDescriptionBody
200RerankResponse (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)
429ErrorBody (application/json)

Documents ​

File uploads and document parsing, billed per page.

GET /v1/files ​

Requires an API key.

StatusDescriptionBody
200FileList (application/json)

POST /v1/files ​

Uploads a document (the request body is the file). Kept for 30 days.

Requires an API key.

StatusDescriptionBody
201FileView (application/json)
400ErrorBody (application/json)
413ErrorBody (application/json)

GET /v1/files/{id} ​

Requires an API key.

StatusDescriptionBody
200FileView (application/json)
404ErrorBody (application/json)

DELETE /v1/files/{id} ​

Deletes a file and its content.

Requires an API key.

StatusDescriptionBody
204
404ErrorBody (application/json)

POST /v1/parse ​

Parses a document into Markdown, pages and elements. Billed per page.

Requires an API key.

Request body: ParseRequest

StatusDescriptionBody
200ParseResponse (application/json)
400ErrorBody (application/json)
402ErrorBody (application/json)
503ErrorBody (application/json)

Account ​

Keys and account information.

GET /v1/key ​

Returns details and effective limits for the calling API key.

Requires an API key.

StatusDescriptionBody
200KeyInfo (application/json)
401ErrorBody (application/json)
429ErrorBody (application/json)

Schemas ​

BillingOverview ​

FieldTypeDescription
balance_usdstring
held_usdstring
low_balance_threshold_usdstring

CapabilityStatus ​

FieldTypeDescription
models_availableintegerModels with at least one healthy provider, out of all models.
models_totalinteger
statusLevel

ChatChunk ​

FieldTypeDescription
choicesChunkChoice[]
createdinteger
idstring
modelstring
objectstring
provider?string
usage?ChatUsage

ChatMessage ​

FieldTypeDescription
content?MessageContent
name?string
roleRole
tool_call_id?string
tool_calls?ToolCall[]

ChatRequest ​

FieldTypeDescription
max_completion_tokens?integer
max_tokens?integer
messagesChatMessage[]
modelstringA Usefully model ID such as anthropic/claude-opus-5-5, or a bare name like gpt-5-mini when it identifies exactly one model.
n?integer
parallel_tool_calls?boolean
provider?ProviderPreferences
reasoning_effort?stringlow, medium, high (and provider-specific levels).
response_format?object
stop?Stop
stream?boolean
stream_options?StreamOptions
temperature?number
tool_choice?object"auto", "none", "required" or {"type":"function","function":{"name":…}}.
tools?Tool[]
top_p?number
user?string

ChatResponse ​

FieldTypeDescription
choicesChoice[]
createdinteger
idstring
modelstring
objectstring
provider?stringThe provider that served the request.
usage?ChatUsage

ChatUsage ​

FieldTypeDescription
completion_tokensinteger
completion_tokens_details?CompletionTokensDetails
prompt_tokensinteger
prompt_tokens_details?PromptTokensDetails
total_tokensinteger

CheckoutRequest ​

FieldTypeDescription
amount?numberCredits to buy, in currency (default USD). Limits are about $5 to $10,000 in each currency; see GET /v1/currencies. A 3.5% fee is added.
amount_usd?numberDeprecated: same as amount with currency: "USD".
currency?stringUSD (default), INR or EUR.

CheckoutResponse ​

FieldTypeDescription
amountstring
checkout_urlstringSend the customer here to pay.
credit_usdstringThe credits this buys, in USD.
currencystringThe currency charged, and the amounts in it (decimal strings).
feestring
fee_usdstring
session_idstring
totalstring
total_usdstring

Choice ​

FieldTypeDescription
finish_reason?string
indexinteger
messageResponseMessage

ChunkChoice ​

FieldTypeDescription
deltaDelta
finish_reason?string
indexinteger

CompletionTokensDetails ​

FieldTypeDescription
reasoning_tokens?integer

ContentPart ​

A content part. Types we don't translate (audio, files, …) are kept verbatim for OpenAI-compatible providers.

Type: KnownPart | object

CrawlRequest ​

FieldTypeDescription
exclude_paths?string[]Never crawl paths matching these.
include_paths?string[]Only crawl paths matching one of these (* matches anything), e.g. /docs/*.
max_chars?integerTruncate each page's content (default 100,000 characters).
max_depth?integerLink depth from the start page, 0–5 (default 2).
max_pages?integerPages to crawl, 1–1,000 (default 50).
model?string
provider?ProviderPreferences
urlstringThe start page. Only pages on the same host are crawled.
use_sitemap?booleanAlso start from the site's /sitemap.xml (default true).

CreateSession ​

FieldTypeDescription
block_ads?booleanBlock ads (default true).
region?stringus-west-2, us-east-1, eu-central-1 or ap-southeast-1.
timeout_minutes?integerSession length limit in minutes, 1–30 (default 5). Billing stops earlier if you release the session.
viewport?Viewport

CurrencyList ​

FieldTypeDescription
basestringCredits and per-request prices are in this currency.
dataCurrencyView[]
objectstring

CurrencyView ​

FieldTypeDescription
codestring
maxinteger
mininteger
namestring
per_usdnumberUnits of this currency per 1 USD (credits are USD).
presetsinteger[]Suggested purchase amounts, in whole units.
purchasablebooleanWhether credits can be bought in this currency here.
symbolstring

Delta ​

FieldTypeDescription
content?string
refusal?string
role?Role
tool_calls?ToolCallDelta[]

EmbeddingData ​

FieldTypeDescription
embeddingEmbeddingVector
indexinteger
objectstring

EmbeddingInput ​

Type: string | string[] | object

EmbeddingRequest ​

FieldTypeDescription
dimensions?integerOutput size, for models that support shortening.
encoding_format?stringfloat (default) or base64 (little-endian f32 bytes).
inputEmbeddingInput
input_type?stringquery or document, for models that embed them differently (Voyage, Cohere). Ignored by models that don't.
modelstring
provider?ProviderPreferences
user?string

EmbeddingResponse ​

FieldTypeDescription
dataEmbeddingData[]
modelstring
objectstring
provider?string
usageEmbeddingUsage

EmbeddingUsage ​

FieldTypeDescription
prompt_tokensinteger
total_tokensinteger

EmbeddingVector ​

Type: number[] | string

ErrorBody ​

FieldTypeDescription
errorErrorDetail

ErrorDetail ​

FieldTypeDescription
codestringStable machine-readable code, e.g. invalid_api_key.
messagestringHuman-readable explanation. Safe to show end users.
provider?stringUpstream provider involved, when the error came from one.
request_id?string
typeErrorType

ErrorType ​

Type: invalid_request, authentication, permission_denied, not_found, insufficient_credits, rate_limited, provider_error, timeout, content_filtered, internal, service_unavailable

ExtractError ​

FieldTypeDescription
codestring
messagestring

ExtractRequest ​

FieldTypeDescription
include_links?booleanAlso return the absolute links found on each page.
max_chars?integerTruncate each page's content to this many characters (default 100,000).
model?stringExtraction model. Default: usefully/extract.
provider?ProviderPreferences
urlsstring[]1–10 http(s) URLs.

ExtractResponse ​

FieldTypeDescription
modelstring
objectstringAlways extract.results.
resultsExtractResult[]One entry per requested URL, in order.
usageExtractUsage

ExtractResult ​

FieldTypeDescription
error?ExtractError
page?ExtractedPage
provider?stringWhich provider fetched it.
statusstringok or failed.
urlstring

ExtractUsage ​

FieldTypeDescription
cost_usdstring
pagesintegerPages extracted (and billed).

ExtractedPage ​

FieldTypeDescription
contentstringThe page's main content as Markdown.
description?string
final_urlstringWhere the content came from, after redirects.
language?string
links?string[]Absolute http(s) links found on the page (when requested).
published_at?string
site_name?string
titlestring
urlstringThe URL that was requested.

FileList ​

FieldTypeDescription
dataFileView[]
objectstring

FileView ​

FieldTypeDescription
bytesinteger
content_typestring
created_atstring
expires_atstring
filenamestring
idstring
objectstringAlways file.
sha256string

Freshness ​

Type: day, week, month, year

FunctionCall ​

FieldTypeDescription
argumentsstringJSON-encoded arguments.
namestring

FunctionDef ​

FieldTypeDescription
description?string
namestring
parameters?objectJSON Schema for the arguments.
strict?boolean

FunctionDelta ​

FieldTypeDescription
arguments?string
name?string

ImageUrl ​

FieldTypeDescription
detail?string
urlstringAn https:// URL or a data:<mime>;base64,<data> URL.

JobErrorView ​

FieldTypeDescription
codestring
messagestring

JobList ​

FieldTypeDescription
dataJobView[]
objectstring

JobProgress ​

FieldTypeDescription
completedinteger
failedinteger
totalinteger

JobResults ​

FieldTypeDescription
dataobject[]Items in discovery order. For crawls: {url, status, page?, error?}.
next_after?integerPass as after for the next page; absent when there are no more yet.
objectstring

JobView ​

FieldTypeDescription
completed_at?string
created_atstring
error?JobErrorView
idstring
kindstringcrawl.
objectstringAlways job.
progressJobProgress
statusstringqueued, running, succeeded, failed or cancelled.
summaryobjectTotals when finished, e.g. {"pages": 42, "failed": 1, "cost_usd": "0.042"}.

KeyInfo ​

FieldTypeDescription
environmentstringlive or test.
key_idstring
limitsKeyLimits
org_idstring
project_idstring
scopesstring[]Capabilities this key may use. Empty means all.

KeyLimits ​

FieldTypeDescription
daily_spend_limit_micros?integerDaily spend cap in micro-dollars, if set.
requests_per_minuteintegerEffective requests per minute (the lower of key and plan limits).
tokens_per_minuteintegerEffective tokens per minute.

KnownPart ​

Type: object | object

Level ​

Type: operational, degraded, down

MaxPrice ​

FieldTypeDescription
input?number
output?number

MessageContent ​

Type: string | ContentPart[]

Model ​

FieldTypeDescription
capabilitiesModelCapabilities
context_lengthinteger
createdintegerUnix seconds.
description?string
idstring<author>/<name>, e.g. openai/gpt-5-mini. Bare names also work in requests.
namestring
objectstringAlways model.
owned_bystring
pricingModelPricing
providersstring[]Providers that can serve this model, for routing preferences.
typestringchat, embedding or search.

ModelCapabilities ​

FieldTypeDescription
json_modeboolean
toolsboolean
visionboolean

ModelList ​

Lists available models with capabilities and per-million-token prices. No API key needed. The model catalog (OpenAI-compatible list with Usefully extensions).

FieldTypeDescription
dataModel[]
objectstringAlways list.

ModelPricing ​

Prices in USD as decimal strings (exact; never floats).

FieldTypeDescription
currencystringAlways USD.
input_per_million_tokensstring
output_per_million_tokensstring
per_thousand_requests?stringFor models priced per request (search).

ParseRequest ​

FieldTypeDescription
file_id?stringA file from POST /v1/files. Give this or url.
mode?stringfast (default) or premium (complex layouts and scans).
url?stringA public URL of a document. Give this or file_id.

ParseResponse ​

FieldTypeDescription
elementsobject[]Structure: {type: heading|paragraph|table|list, page, text, level?}.
file_idstring
markdownstringThe whole document as Markdown.
metadataobject
modelstring
objectstringAlways parse.result.
pagesobject[]Per-page Markdown ({number, markdown}).
usageParseUsage

ParseUsage ​

FieldTypeDescription
cost_usdstring
pagesinteger

PromptTokensDetails ​

FieldTypeDescription
cached_tokens?integer

ProviderPreferences ​

FieldTypeDescription
allow_fallbacks?boolean
data_policy?stringzdr, no_training or any.
ignore?string[]Never use these providers.
max_price?MaxPrice
only?string[]Only use these providers.
order?string[]Provider IDs to try first, in order.
sort?stringprice, latency or throughput. Default: registry priority.

ProviderStatus ​

FieldTypeDescription
error_rate?numberShare of recent requests that failed (0–1), when there's traffic.
latency_ms?numberMoving average latency of successful requests.
statusLevel

Readiness ​

FieldTypeDescription
databasestring
redisstring
statusstringok or unavailable.

RerankRequest ​

FieldTypeDescription
documentsstring[]1–1,000 texts.
modelstringA model with type rerank, e.g. cohere/rerank-v3.5.
provider?ProviderPreferences
querystring
return_documents?booleanInclude each document's text in the results.
top_n?integerHow many to return, best first (default: all).

RerankResponse ​

FieldTypeDescription
modelstring
objectstringAlways rerank.
providerstring
resultsRerankResult[]Best first.
usageRerankUsage

RerankResult ​

FieldTypeDescription
document?string
indexintegerPosition in the request's documents.
relevance_scorenumber

RerankUsage ​

FieldTypeDescription
cost_usdstring
search_unitsinteger
total_tokensinteger

ResearchRequest ​

FieldTypeDescription
depth?stringquick, standard (default) or deep.
max_cost_usd?numberStop spending past this (default $1, at most $20). The report is still written.
model?stringThe model that plans, reflects and writes (default anthropic/claude-sonnet-5-5).
questionstringThe question to research.

ResponseMessage ​

FieldTypeDescription
content?string
refusal?string
roleRole
tool_calls?ToolCall[]

Role ​

Type: system, developer, user, assistant, tool

RunRequest ​

FieldTypeDescription
codestringThe code to run (≤ 100 KB).
env_vars?objectEnvironment variables for the code.
language?stringpython (default), javascript, typescript, r, java or bash.
timeout_secs?integerExecution limit in seconds, 1–300 (default 60).

RunResponse ​

FieldTypeDescription
duration_msinteger
error?object{name, value, traceback} if the code raised or timed out.
objectstringAlways sandbox.run.
resultsobject[]Rich outputs (the last expression's value, charts, images as base64 PNG, HTML…).
stderrstring
stdoutstring
truncatedbooleanOutput beyond 100,000 characters per stream (or 20 results) was cut.
usageRunUsage

RunUsage ​

FieldTypeDescription
cost_usdstring
secondsintegerSandbox seconds billed.

SearchRequest ​

FieldTypeDescription
exclude_domains?string[]
freshness?Freshness
include_content?booleanReturn each page's text (up to max_content_chars).
include_domains?string[]
max_content_chars?integer
model?stringSearch model. Default: usefully/web-search.
num_results?integer1–20, default 10.
provider?ProviderPreferences
querystring

SearchResponse ​

FieldTypeDescription
modelstring
objectstring
providerstringThe engine that answered.
querystring
resultsSearchResult[]
usageSearchUsage

SearchResult ​

FieldTypeDescription
content?stringPage text, when include_content was requested.
published_at?stringRFC 3339, when the engine knows it.
score?number
snippetstringA short excerpt (≤300 characters).
titlestring
urlstring

SearchUsage ​

FieldTypeDescription
cost_usdstring
requestsinteger

SessionList ​

FieldTypeDescription
dataSessionView[]
objectstring

SessionView ​

FieldTypeDescription
billed_minutes?integerMinutes billed, once ended.
connect_url?stringCDP WebSocket URL (only when the session is created).
cost_usd?string
created_atstring
ended_at?string
expires_atstring
idstring
objectstringAlways browser.session.
statusstringrunning, completed or expired.
timeout_minutesinteger

SettingsUpdate ​

Unknown fields are refused, so a misspelt or retired setting (such as the old auto_topup_* fields) fails loudly instead of being ignored.

FieldTypeDescription
low_balance_threshold_usd?number

Status ​

FieldTypeDescription
capabilitiesobjectchat, embedding, search.
providersobject
statusLevelWorst capability level.
updated_atstring

Stop ​

Type: string | string[]

StreamOptions ​

FieldTypeDescription
include_usage?boolean

Tool ​

FieldTypeDescription
functionFunctionDef
typestring

ToolCall ​

FieldTypeDescription
functionFunctionCall
idstring
typestring

ToolCallDelta ​

FieldTypeDescription
function?FunctionDelta
id?string
indexinteger
type?string

Viewport ​

FieldTypeDescription
heightinteger
widthinteger