DocsReferenceAPI reference
POST /v1/stack
Choose a stack for an agent: the parameters, answers, errors and examples of POST /v1/stack in the Rhumb API.
Choose a stack for an agent
For the systems an agent has to work with, where it runs and what it may do: one choice a system (its owner's own MCP server or its own command-line tool, or none with the reason), the model (as /v1/resolve answers it, when model names providers), the owners' skills, warnings and a .mcp.json to start from.
- Fixed rules over public records, in order: only the servers a system's owner publishes, never another publisher's, however popular; for a cloud agent the first with a Streamable HTTP remote a client can use as it is; for a local agent the system's command-line tool when one is curated (unless
preferis server), else a remote server, else a package pinned to one version that the harness can start. - A choice with a known problem is still the choice, with the problem in
warnings. - No model reads the request, and nothing is reviewed: an answer is a reading of public records on the catalogs' dates, and
trust: first_partysays only who publishes the server. - The config is built from parts checked by shape, with a placeholder for every value a person supplies.
- Needs the
resolvescope. - The same answer for the same two catalog versions and request; cache it.
- Counted; a
modelthat fits nothing is still a 200, with the reason inmodel.none.
Example: POST /v1/stack
Parameters
None.
Responses
200body:StackResponseThe 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" } }429body: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" } }503body:Erroragent_catalog_unavailable: the API holds no agent catalog (systems, servers, skills) to answer from; /v1/health says which it has. Not counted against the quota. The rest of the API is not affected.
Headers:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Limit,X-Quota-Remaining,X-Quota-Reset,X-Overage-Used,X-Overage-Limitagent_catalog_unavailable { "error": { "code": "agent_catalog_unavailable", "message": "The agent catalog is not available: no agent catalog has been published" } }