Skip to the content

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 prefer is 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_party says 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 resolve scope.
  • The same answer for the same two catalog versions and request; cache it.
  • Counted; a model that fits nothing is still a 200, with the reason in model.none.

Example: POST /v1/stack

Parameters

None.

Responses

200body: StackResponse

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"
  }
}
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"
  }
}
503body: Error

agent_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-Limit

agent_catalog_unavailable
{
  "error": {
    "code": "agent_catalog_unavailable",
    "message": "The agent catalog is not available: no agent catalog has been published"
  }
}