Skip to the content

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 constraints always win over the decision model, and sources says 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_used is true, so the call never fails because of the decision model.
  • decision.model: openai (default, OpenAI's Decisions API) or local (allow_remote: false also 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) when reading.ensemble_helps is true, an escalation when constraints give 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: PlanResponse

The 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-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"
  }
}