---
title: "Ask"
method: POST
path: "/api/v2/account/ask"
tags: ["Account"]
---

# Ask

`POST /api/v2/account/ask`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/account/ask`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Session-Token`

One question about a world, answered from the elements the client sends
(the ones its own search found, as text), by a model the platform pays for
and meters against the account's daily token rating. Body: `world_id`,
`question`, `context` (a list of elements as text). The model answers only from the context and
says so when it does not hold the answer. An account credential (Bearer
`ow_a_`, a signed-in session, or a phone's `X-Session-Token`).

## Request body

- object
  - `world_id` string, uuid, required: A world this account owns or is a member of.
  - `question` string, required
  - `context` string[], required: One element as text per item, 12000 characters in all.

## Response `200`

The answer: `answer` (text; "The world doesn't say." when the elements do not hold it), `model`, `stop_reason`, `usage` {input_tokens, output_tokens}, `remaining` (how many more calls of this one's size fit in what this account has left today), `tokens_remaining` (the account's tokens left today after this call) and `token_rating` (the account's daily token rating).

- object
  - `answer` string, required
  - `model` string, required
  - `stop_reason` string, required
  - `usage` object, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
  - `remaining` integer, required: How many more calls of this one's size fit in what this account has left today.
  - `tokens_remaining` integer, required: The account's tokens left today after this call.
  - `token_rating` integer, required: The account's daily token rating.

## Other responses

- `401`: Missing or invalid account credential (Bearer ow_a_ token or session).
- `404`: The world is not one this account owns or is a member of (not_found).
- `422`: world_id, question (1 to 500 characters) or context (1 to 8 non-empty strings, each at most 2000 characters, 12000 in all) is missing or malformed; `param` names it.
- `429`: This account has used today's token rating (quota_exceeded): fewer tokens are left than an answer may take. Retry-After says when the rating resets (midnight UTC). Or too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds.
- `502`: The model gave no answer (ask_failed); nothing was counted.
- `503`: Asking is not switched on, or is paused for the day (ask_unavailable), nothing counted; or every request slot stayed full (server_busy, with Retry-After).

## Changes

- **2026-10-20** `78df39c4c62e`: 6 warning
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `404`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `429`
  - …2 more
- **2026-10-20** `4dd5b1cd0687`: 12 warning
  - added the new `character_taken` enum value to the `error/code` response property for the response status `401`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `404`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `429`
  - …8 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/account/ask/post.md)

---

[API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/78df39c4c62e?raw)