---
title: "Sort Notes"
method: POST
path: "/api/v2/account/sort"
tags: ["Account"]
---

# Sort Notes

`POST /api/v2/account/sort`

## Request

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

Sort a user's unsorted notes into proposed changes to a world: new
elements, text to add, links to make, and questions where the notes are
ambiguous. Body: `world_id`, `notes` (a list of notes: text, or a
photographed note uploaded to this world's media, with optional text) and `slice`
(the elements the client's own search found for them: id, type, name and an
optional anchor, a short phrase that tells two same-named elements apart).
The answer only proposes; the client applies what the user accepts. A sort
spends its tokens from the account's daily token rating, as ask does. 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.
  - `notes` union[], required: 16000 characters of text in all, at most 4 images.
    - union
      - string
      - object: A note with a photograph: text (may be empty) and image_url, an image uploaded into this world (https://media.onlyworlds.com/u/<world_id>/...). At least one of the two.
        - `text` string
        - `image_url` string, uri
  - `slice` object[]
    - `id` string, uuid, required
    - `type` 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone', required
    - `name` string, required
    - `anchor` string: A short phrase that tells two same-named elements apart.

## Response `200`

The proposed changes: `rows`, each one of four kinds (`make` a new element; `add_to` text appended to a field of a slice element; `link` one slice element to another through a field; `ask` a question with `candidates` when a name matches several slice elements or the sorter is unsure, and optionally `then`, the add_to or link row it stands for without its target), each with the `source_line` it came from; `not_proposed` (lines not placed, each with a `reason`); `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). Every id in a row is an id from the request's slice; a row naming any other id is moved to not_proposed. Names, types and anchors of the elements a row points at are the slice's own. Nothing is written to the world.

- object
  - `rows` object[], required
    - `kind` 'make' | 'add_to' | 'link' | 'ask', required
    - `source_line` string, required
    - `proposal` object
      - `type` string, required
      - `name` string, required
      - `description` string, required
    - `target` object
      - `id` string, uuid, required
      - `name` string, required
      - `type` string, required
      - `anchor` string
    - `field` string
    - `op` 'append'
    - `value` string
    - `value_id` string, uuid
    - `value_name` string
    - `question` string
    - `candidates` object[]
      - `id` string, uuid, required
      - `name` string, required
      - `type` string, required
      - `anchor` string
    - `then` object
      - `kind` 'add_to' | 'link', required
      - `field` string, required
      - `op` 'append'
      - `value` string
      - `value_id` string, uuid
      - `value_name` string
  - `not_proposed` object[], required
    - `source_line` string, required
    - `reason` 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, notes or slice is missing or malformed; `param` names it. notes: 1 to 8, each a string or an object {text, image_url} with at least one of the two; text at most 4000 characters a note, 16000 in all; at most 4 images, each an https://media.onlyworlds.com/ URL under this world's upload prefix u/<world_id>/. slice: 0 to 100 objects, each with a UUID id, one of the 22 element types in lowercase, a name, and an optional anchor of at most 120 characters.
- `429`: This account has used today's token rating (quota_exceeded): fewer tokens are left than a sort may take (a sort draws on the same rating as ask). 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 usable answer (ask_failed); nothing was counted.
- `503`: Sorting 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/sort/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)