Skip to the content

DocsReferenceAPI reference

GET /v1/purposes

List purpose presets: the parameters, answers, errors and examples of GET /v1/purposes in the Rhumb API.

List purpose presets

Purpose presets usable as purpose in /v1/resolve.

  • Free.

Example: GET /v1/purposes

Parameters

None.

Responses

200body: PurposesList

The answer. 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

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