DocsReferenceAPI reference
POST /v1/plan
Plan a request from its prompt and tags: the parameters, answers, errors and examples of POST /v1/plan in the Rhumb API.
Plan a request from its prompt and tags
Reads a request (a prompt, tags and attachment types) into a need, then resolves it as /v1/resolve does.
- Facts come first (attachment types set input needs, the prompt's size sets min_context and usage), then tags (a synonym list for origin, budget, capabilities and purpose aliases), then the decision model for the rest; facts and
constraintsalways win over the decision model, andsourcessays where each part came from. - The decision model reads at most the first 4,000 tokens of the prompt within the decision budget (1500 ms by default); on a timeout, an error or an invalid answer the local classifier reads it instead and
decision.fallback_usedis true, so the call never fails because of the decision model. decision.model: openai (default, OpenAI's Decisions API) or local (allow_remote: falsealso keeps the prompt on the server); test keys always read locally.- The prompt is sent only to the decision model you choose and is never stored or logged; readings are cached for 24 hours under a keyed hash.
- With
shape: "auto"the reading chooses the shape: a team (the request's strategy or roles, the purpose's, else red-team for an adversarial request and expert-panel otherwise) whenreading.ensemble_helpsis true, an escalation whenconstraintsgive a length, else one model. - Counts as 5 calls against the quota, since each reading calls the decision model; errors and no_candidate are not counted.
Example: POST /v1/plan
Parameters
None.
Responses
200body:PlanResponseThe answer. Counts as 5 calls 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" } }