Skip to the content

DocsReferenceAPI reference

GET /v1/resolve

Resolve a need to a model: the parameters, answers, errors and examples of GET /v1/resolve in the Rhumb API.

Resolve a need to a model

A structured need (a task or purpose, your providers, and constraints) to the model to call, with the same model on your other providers and the next alternatives.

  • shape=team answers models in named roles (team), from a strategy preset or your own roles, under one budget for the whole team; shape=escalation answers an ordered list of steps (escalation), or one model plus the team to escalate to.
  • A team or escalation is one call.
  • Local runtimes (ollama, lmstudio, llama.cpp, mlx, webllm) are providers like any other: send the device's max_memory_gb, max_vram_gb and max_disk_gb with them, and a local answer carries its quantization, license and requirements (memory at the request's context).
  • Local offerings are free, count as the cheap band, and their score has the quantization's penalty taken off.
  • The same answer for the same catalog version, need and shape; cache it.
  • Counted.

Example: GET /v1/resolve?task=text.chat&budget=cheap&providers=gemini,openrouter

Parameters

Parameters of resolve
NameInTypeDescription
providersrequiredquerystringRequired. Provider names you have accounts with, in order of preference for ties. Never keys. Comma-separated.Example: gemini,openrouter
taskquerystringA task, e.g. text.chat. Required unless purpose is given.Example: text.chat
purposequerystringA purpose preset id or alias, e.g. read-receipts.
needsquerystringRequired capabilities, optionally with a level: "input.pdf:native". Comma-separated.
provider_termsquerystringYour terms per provider: "openrouter:byok", "gemini:free_tier", "openai:discount:0.2". Comma-separated.
originquerystringModel maker countries or groups: "us", "eu", "not:cn". Comma-separated.
origin_strictquery"true" | "false"Also require a fine-tune's base model maker to match.
budgetquery"cheap" | "medium" | "premium"Thirds of the market's prices for the task.Example: cheap
max_pricequerystringHard cap on the typical call, in USD, e.g. 0.002, at the day's highest rate.
optimizequery"cost" | "quality" | "value"cost (default), quality or value.
quality_marginquerystringFor optimize=cost: how far below the best score still counts (default 0.05).
input_tokensquerystringExpected input tokens per call.
output_tokensquerystringExpected output tokens per call.
cached_input_tokensquerystringInput tokens served from the provider's cache.
prompt_tokensquerystringPrompt size, for long-prompt price tiers.
imagesquerystringInput images per call.
output_imagesquerystringGenerated images per call.
resolutionquerystringImage resolution key, e.g. "1k".
pagesquerystringPDF pages per call.
audio_secondsquerystringAudio seconds per call.
video_secondsquerystringVideo seconds per call.
min_qualityquerystringMinimum quality score, 0–1.
min_contextquerystringMinimum context window in tokens.
max_memory_gbquerystringLocal runtimes: the device's memory in GB (10^9 bytes). A local offering fits when its weights, KV cache at the request's min_context (8,192 tokens when smaller) and runtime overhead fit. Cloud offerings are not limited.
max_vram_gbquerystringLocal runtimes: GPU memory in GB, for a full offload. On Apple silicon send the GPU's share of unified memory (macOS allows about 2/3 by default, 3/4 above 36 GB) and the total as max_memory_gb.
max_disk_gbquerystringLocal runtimes: free disk in GB for the weights.
released_afterquerystringYYYY-MM-DD.
allow_previewquery"true" | "false"Allow preview models (default false).
allow_trialquery"true" | "false"Allow trial offerings, which aren't for production (default false).
allow_closedquery"true" | "false"Allow models the provider has closed to new accounts. Send true only if your account used them before (default false).
excludequerystringModel ids, vendors, or provider:model pairs to leave out. Comma-separated.
licensequerystringAccepted open-weight licenses. Comma-separated.
service_tierquery"standard" | "batch" | "flex" | "priority"
hoursquerystringUTC hours you make your calls in, every day, as HH-HH ranges: 09-17, or 22-06 past midnight, or 00-24. A price with cheaper hours then ranks on its average over these hours instead of over a flat week. Comma-separated.
currencyquerystringAdds the typical call converted to this currency, e.g. EUR.
shapequery"single" | "team" | "escalation"single (default, or the purpose's), team (with strategy or roles) or escalation (a ladder of length steps, or one model then a team with strategy or roles).
strategyquery"debate" | "red-team" | "competitive" | "hierarchical" | "expert-panel" | "collaborative"A team strategy preset: its roles and their rules.
rolesquerystringTeam roles: "name:count" pairs, comma-separated (lead:1,workers:4), or a JSON object of role name to { count, task, needs, min_quality, optimize, distinct_vendor_from, distinct_family, judges }. Overrides and extends the strategy's roles.
lengthquerystringEscalation steps, 1–5 (default 3).
synthesisquery"true" | "false"Add a synthesizer role to the team.
origin_mixquerystringTeam origin rules: "eu:>=1", "cn:<=0", "us:=2". Comma-separated.
providers_distinctquery"true" | "false"Every team member, or escalation step, on a different provider.

Responses

200body: Resolution

The answer. Counts one call against the quota.

Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Overage-Used, X-Overage-Limit

400body: Error

invalid_request (an unknown name or a malformed value: field and allowed say which) or key_in_query (keys go in a header, never the URL).

Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Overage-Used, X-Overage-Limit

invalid_request
{
  "error": {
    "code": "invalid_request",
    "message": "Unknown task \"text.chit\"",
    "field": "task",
    "allowed": [
      "text.chat",
      "text.embed"
    ]
  }
}
key_in_query
{
  "error": {
    "code": "key_in_query",
    "message": "API keys are not accepted in the query string; send them in the Authorization header. Rotate a key that was put in a URL."
  }
}
401body: Error

missing_api_key (no key sent) or invalid_api_key (unknown, disabled, revoked or expired).

missing_api_key
{
  "error": {
    "code": "missing_api_key",
    "message": "Send your API key as `Authorization: Bearer <key>`"
  }
}
invalid_api_key
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is not valid"
  }
}
403body: Error

account_suspended; insufficient_scope (the key lacks the scope the endpoint needs: required_scope names it); ip_not_allowed (the key's IP allowlist does not include the caller); wrong_key_kind (a management key, which calls only the key-management API); or (POST /v1/plan) decision_model_not_allowed: decision.model=jev is for internal accounts only.

account_suspended
{
  "error": {
    "code": "account_suspended",
    "message": "This account is suspended"
  }
}
insufficient_scope
{
  "error": {
    "code": "insufficient_scope",
    "message": "This key lacks the `resolve` scope this endpoint needs",
    "required_scope": "resolve"
  }
}
ip_not_allowed
{
  "error": {
    "code": "ip_not_allowed",
    "message": "This key may not be used from this IP address"
  }
}
wrong_key_kind
{
  "error": {
    "code": "wrong_key_kind",
    "message": "Management keys only call the key-management API (/api/v1/manage); use a live or test key here"
  }
}
decision_model_not_allowed
{
  "error": {
    "code": "decision_model_not_allowed",
    "message": "decision.model=jev is available to internal accounts only; use openai or local",
    "field": "decision.model",
    "allowed": [
      "openai",
      "local"
    ]
  }
}
413body: Error

request_too_large: request bodies are limited to 64 KB.

request_too_large
{
  "error": {
    "code": "request_too_large",
    "message": "Request bodies are limited to 64 KB"
  }
}
422body: NoCandidate

no_candidate: nothing on your providers meets the need. Says how many candidates each constraint removed, and the nearest miss. Not counted against the quota.

Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Overage-Used, X-Overage-Limit

429body: Error

rate_limited (the per-minute rate; Retry-After says when to try again) or quota_exhausted (the period's calls are used up; no Retry-After, resets_at and upgrade_url instead).

Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Overage-Used, X-Overage-Limit

rate_limited
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 10 requests a minute reached"
  }
}
quota_exhausted
{
  "error": {
    "code": "quota_exhausted",
    "message": "Your plan's 1,000 calls for this period are used up",
    "resets_at": "2026-12-01T00:00:00.000Z",
    "upgrade_url": "https://rhumbdata.com/app/billing"
  }
}