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 ownroles, 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
| Name | In | Type | Description |
|---|---|---|---|
providersrequired | query | string | Required. Provider names you have accounts with, in order of preference for ties. Never keys. Comma-separated.Example: gemini,openrouter |
task | query | string | A task, e.g. text.chat. Required unless purpose is given.Example: text.chat |
purpose | query | string | A purpose preset id or alias, e.g. read-receipts. |
needs | query | string | Required capabilities, optionally with a level: "input.pdf:native". Comma-separated. |
provider_terms | query | string | Your terms per provider: "openrouter:byok", "gemini:free_tier", "openai:discount:0.2". Comma-separated. |
origin | query | string | Model maker countries or groups: "us", "eu", "not:cn". Comma-separated. |
origin_strict | query | "true" | "false" | Also require a fine-tune's base model maker to match. |
budget | query | "cheap" | "medium" | "premium" | Thirds of the market's prices for the task.Example: cheap |
max_price | query | string | Hard cap on the typical call, in USD, e.g. 0.002, at the day's highest rate. |
optimize | query | "cost" | "quality" | "value" | cost (default), quality or value. |
quality_margin | query | string | For optimize=cost: how far below the best score still counts (default 0.05). |
input_tokens | query | string | Expected input tokens per call. |
output_tokens | query | string | Expected output tokens per call. |
cached_input_tokens | query | string | Input tokens served from the provider's cache. |
prompt_tokens | query | string | Prompt size, for long-prompt price tiers. |
images | query | string | Input images per call. |
output_images | query | string | Generated images per call. |
resolution | query | string | Image resolution key, e.g. "1k". |
pages | query | string | PDF pages per call. |
audio_seconds | query | string | Audio seconds per call. |
video_seconds | query | string | Video seconds per call. |
min_quality | query | string | Minimum quality score, 0–1. |
min_context | query | string | Minimum context window in tokens. |
max_memory_gb | query | string | Local 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_gb | query | string | Local 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_gb | query | string | Local runtimes: free disk in GB for the weights. |
released_after | query | string | YYYY-MM-DD. |
allow_preview | query | "true" | "false" | Allow preview models (default false). |
allow_trial | query | "true" | "false" | Allow trial offerings, which aren't for production (default false). |
allow_closed | query | "true" | "false" | Allow models the provider has closed to new accounts. Send true only if your account used them before (default false). |
exclude | query | string | Model ids, vendors, or provider:model pairs to leave out. Comma-separated. |
license | query | string | Accepted open-weight licenses. Comma-separated. |
service_tier | query | "standard" | "batch" | "flex" | "priority" | |
hours | query | string | UTC 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. |
currency | query | string | Adds the typical call converted to this currency, e.g. EUR. |
shape | query | "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). |
strategy | query | "debate" | "red-team" | "competitive" | "hierarchical" | "expert-panel" | "collaborative" | A team strategy preset: its roles and their rules. |
roles | query | string | Team 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. |
length | query | string | Escalation steps, 1–5 (default 3). |
synthesis | query | "true" | "false" | Add a synthesizer role to the team. |
origin_mix | query | string | Team origin rules: "eu:>=1", "cn:<=0", "us:=2". Comma-separated. |
providers_distinct | query | "true" | "false" | Every team member, or escalation step, on a different provider. |
Responses
200body:ResolutionThe 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-Limit400body:Errorinvalid_request (an unknown name or a malformed value:
fieldandallowedsay 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-Limitinvalid_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:Errormissing_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:Erroraccount_suspended; insufficient_scope (the key lacks the scope the endpoint needs:
required_scopenames 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=jevis 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:Errorrequest_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:NoCandidateno_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-Limit429body:Errorrate_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_atandupgrade_urlinstead).Headers:
Retry-After,RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Limit,X-Quota-Remaining,X-Quota-Reset,X-Overage-Used,X-Overage-Limitrate_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" } }