---
name: set-api-connection
description: How to connect to the Set World API. Use before the first call to check the service, discover endpoints from /api/spec, read the error envelope and status codes, pass seeds, keep contentVersion for replay, request tables as CSV, or connect an agent over MCP. Includes the schemas of the spec document, the error envelope and the MCP tools.
license: "Free to use when obtained from set.world, commercially too (the API, what it returns and the skills). Its models, animations and textures, Anima included, are CC BY 4.0: free to use with attribution to Jimmy Lee (j@internet.dev). The source code of Set is © Jimmy Lee under CC BY-NC 4.0 and its commercial use needs a paid waiver."
metadata:
  version: "0.15.35"
  title: API connection
---

# API connection

Set is a stateless JSON API at `https://set.world`. There is no key, account, SDK or rate-limit header. Every call is a `GET` with query parameters, except the MCP endpoint, which takes `POST`. This skill owns the conventions every other skill relies on.

## Check the connection

```sh
curl https://set.world/api
```

```json
{ "hello": "set world" }
```

It returns this greeting and nothing else.

## Discover the endpoints

```sh
curl https://set.world/api/spec
```

```ts
type Spec = { version: 1; endpoints: SpecEntry[] };

type SpecEntry = {
  method: 'GET' | 'POST';
  path: string;                                      // ":name" marks a path segment
  query?: string;                                    // the parameters, in prose
  example?: string;                                  // a path you can call as written
  summary: string;
  scenario: { use: string; returns: string };        // labels for people
  workspace: { title: string; description: string }; // labels for people
};
```

One entry, with its copy text left out:

```json
{
  "method": "GET",
  "path": "/api/roll/item",
  "workspace": { "title": "…", "description": "…" },
  "query": "seed?",
  "summary": "…",
  "scenario": { "use": "…", "returns": "…" }
}
```

`query` is prose, not a schema; the skill that owns each endpoint has its schema.

## Requests

- **Method.** `GET`, no body. Structured parameters (`override`, `actors`) are URL-encoded JSON.
- **CORS.** Open for `GET`, `POST` and `OPTIONS` from any origin, so a browser game can call Set directly.
- **Vectors.** Stats and item vectors are dash-joined integers: `stats=14-12-10-11-13-16-12-14-11`, `rolls=` with 19 numbers.
- **Repeats.** A repeated parameter uses its first value.
- **Malformed is an error, not an omission.** `seed=abc` returns 400. An empty `seed=` means unseeded; every other empty value is invalid.

## Responses and errors

Successes return the payload directly, never wrapped. Failures return one envelope:

```ts
type ErrorCode = 'INVALID_SEED' | 'INVALID_INDEXES' | 'INVALID_QUERY' | 'INVALID_FORMAT' | 'INVALID_TIER' | 'INVALID_ORBS' | 'INVALID_BUDGET' | 'INVALID_STATS' | 'INVALID_RANGE' | 'INVALID_OVERRIDE' | 'INVALID_KIND' | 'INVALID_CLASS' | 'INVALID_DROP' | 'INVALID_LEVEL' | 'INVALID_TALENTS' | 'INVALID_NAME' | 'INVALID_EQUIPMENT_BONUS' | 'INVALID_COMBAT_INPUT' | 'VERSION_MISMATCH' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED';
type ErrorEnvelope = { error: { code: ErrorCode; message: string; field?: string } };
```

```json
{ "error": { "code": "INVALID_SEED", "message": "seed must be an integer in [0, 4294967295]", "field": "seed" } }
```

| Status | Meaning |
| --- | --- |
| 400 | Invalid input; `field` names the parameter |
| 404 | Unknown guide, skill or table |
| 405 | Wrong method (guide, skill, combat calculator and MCP routes) |
| 409 | A `contentVersion` or `rulesVersion` precondition on `/api/basic-lightweight-combat` that differs from the server's. The whole stamp is compared, release included |

Skills, hosted guides and every success its URL decides are sent with `Cache-Control: public, max-age=300`, so a copy can be up to 5 minutes old: the tables and specs, the calculators and appraisals, and a roll, craft or drop that names a `seed`. A stored roll keeps the `contentVersion` it was rolled under, so read that field to tell which snapshot it belongs to. A roll, craft or drop with no `seed` sends `no-store`, as do the combat calculator's and the MCP endpoint's successful replies. An error carries no cache header.

## Seeds, `contentVersion` and replay

- `seed` is an unsigned 32-bit integer, 0 to 4294967295. Omit it for a random result, drawn from the server's cryptographic random source; the response then carries `"seed": null`. Which of Set's values are fixed, seeded or fresh: [Randomness](https://set.world/skills/anima-randomness).
- Every seeded response carries `seed` and `contentVersion`. The same operation, effective inputs, seed and `contentVersion` reproduce the same object.
- `contentVersion` is `8.<fingerprint>` (now `8.1bmmTgz1B0Y9UKhiu84STg`): a rules revision, then a 22-character base64url fingerprint (the first 128 bits of a SHA-256) of the item tables, talents, advantages, disadvantages and classes. A table edit moves the fingerprint; an output-affecting code change bumps the revision.
- Old snapshots are not hosted. Keep full objects when you need history; a seed is not a save file.
- To expand one seed into many, see [Rolling a group](https://set.world/skills/rolling-a-group).

What to store with anything you generate:

```ts
type Replay = {
  operation: string;                  // "/api/roll/character"
  inputs: Record<string, string>;     // every effective parameter except the seed
  seed: number | null;
  contentVersion: string;             // "8.1bmmTgz1B0Y9UKhiu84STg"
};
```

## Rule stamps

Every rule Set publishes carries a stamp, `set-world-<release>-<system>-<n>`: Set's namespace, the release that serves it (`0-15-35`, the skills' `metadata.version` with dashes), then the rule. The API's rules carry one, such as the lottery's `set-world-0-15-35-lottery-5` that a craft response prints, and so do the Anima System's, such as `set-world-0-15-35-anima-scaling-7` for level and orb scaling or `set-world-0-15-35-magic-11` for magic. The skills print the current stamp beside every rule they describe.

- **`set-world-` is Set's namespace.** A stamp that starts with it names a rule exactly as set.world ships it.
- **Two numbers, two meanings.** The release part changes with every release of Set, whether or not the rule did; the number at the end rises only when that rule changes. To ask whether two stamps name the same rule, compare what follows the release (`set-world-0-15-35-anima-scaling-7` and a stamp from an older release that also ends in `-anima-scaling-7` are the same rule).
- **Name your own rules in your own namespace.** When your world or game changes one of Set's rules or adds one, give its stamp your own prefix (`mygame-1-0-0-magic-1`), never `set-world-`, so anyone reading a saved record can tell Set's rules from yours.
- **A stamp names a rule and nothing more.** It is not part of `contentVersion` and never seeds a result, so a stamp alone never changes what a seed produces.
- **Saved links.** The character page reads the stamp in a saved link's `simulation` parameter by its rule alone, so a link saved under an older release, or before the release joined the stamp (`anima-scaling-7`, `set-world-anima-scaling-7`), still replays while the rule is the same.

## One soul per call

Every creating request (roll, craft, drop, combat damage) waits in one process-local queue after validation. A busy server makes the next caller wait; that wait is the throttle. There is no `count=` parameter and no batch endpoint, so send roster requests one at a time.

## Tables as CSV

Reference endpoints (`/api/stats`, `/api/slots`, `/api/tables`, `/api/tables/:table`, `/api/talents`, `/api/classes`, `/api/advantages`, `/api/disadvantages`, `/api/effects`, `/api/traits/impacts`, `/api/attributes/spec`) return JSON by default and CSV with `format=csv`: RFC 4180, a header row, CRLF line ends, quoted fields where needed, and a space between the values of a list inside one cell. Any other `format` returns 400 with `INVALID_FORMAT`.

Each table's own skill shows its CSV call and columns.

## Query a table

All of Set's data is served by an endpoint, and the list endpoints take filters, so a game can ask for one row instead of the table:

| Endpoint | Exact filters | `q=` searches |
| --- | --- | --- |
| `/api/tables/:table` | `index=`, `name=` | `name` |
| `/api/talents` | `id=`, `name=` | `name`, `flavor` |
| `/api/classes` | `name=`, `mainhand=` | `name`, `mainhand`, `flavor` |
| `/api/advantages` | `id=`, `name=`, `tier=`, `primary=`, `secondary=` | `name` |
| `/api/disadvantages` | `id=`, `name=`, `tier=`, `primary=`, `secondary=` | `name` |
| `/api/effects` | `name=` | `name`, `description` |

An exact filter matches the whole value of the column it is named after, ignoring case; `q=` matches text anywhere in the searched columns, ignoring case. Every filter names a column of the endpoint's CSV, so the advantage and disadvantage lists filter by the impact their CSV shows even though their JSON rows carry only `id` and `name`.

```sh
curl 'https://set.world/api/classes?mainhand=sword'
```

```json
{
  "count": 1,
  "data": [{ "name": "Adventurer", "flavor": "The Adventurer arrived upon these shores seeking a tale; what was found is a story that permits no departure", "mainhand": "sword" }]
}
```

Filters combine with each other and with `format=csv`. The response keeps the shape of the unfiltered one, and only the list narrows: `/api/classes` and `/api/effects` report `count` as the rows returned; `/api/tables/:table` keeps the whole table's `count` and `totalWeight`, so its weights and probabilities still read against the full table; the talent and trait lists carry no `count`. A filter that matches nothing returns an empty list, and an empty filter value returns 400 with `INVALID_QUERY`. The map of every data endpoint is in [AGENTS.md](https://set.world/AGENTS.md).

## Connect over MCP

`https://set.world/mcp` (the endpoint `/api/mcp`) is a Model Context Protocol server over Streamable HTTP: JSON responses, no event stream, no session and no key. It runs no model and adds no rule; it forwards to the same endpoints and skills.

```sh
claude mcp add --transport http set https://set.world/mcp
```

- **Transport.** `POST` only, with one JSON-RPC 2.0 message as the body. Any other method returns 405 with the error envelope and `Allow: POST, OPTIONS`. A request gets one JSON-RPC response and a notification gets 202 with no body. A body that is not JSON is 400 with error `-32700` (sent as `application/json`, the host refuses it first with a plain-text 400 `Invalid JSON`), and a message that is not JSON-RPC 2.0 is 400 with `-32600`.
- **Protocol versions.** The server speaks `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, and serves both eras on the one endpoint:
  - **Stateless (`2026-07-28`).** There is no handshake. Every request names its version in `params._meta["io.modelcontextprotocol/protocolVersion"]` and carries the `MCP-Protocol-Version` and `Mcp-Method` headers, plus `Mcp-Name` (the tool name or resource URI) on `tools/call` and `resources/read`. A missing or different header is 400 with error `-32020`; a `_meta` version other than `2026-07-28` is 400 with error `-32022` and `data: { supported, requested }`; an unknown method is 404 with `-32601`. Every result carries `resultType: "complete"` and the server's identity in `_meta["io.modelcontextprotocol/serverInfo"]`; discovery, lists and reads add `ttlMs: 300000` and `cacheScope: "public"`. Call `server/discover` for the versions, capabilities and instructions up front.
  - **Initialize (`2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`).** A request without that `_meta` field is served under the earlier revisions: `initialize` answers with the version you ask for when it is one of these, and with `2025-11-25` otherwise, and `ping` answers. A batch (an array of messages) gets an array of responses; an empty batch is 400 with `-32600`. Batches are served only on these revisions: a batched message with the stateless `_meta` field is `-32600`, so send stateless requests one per `POST`.
- **Identity.** `serverInfo.version` is the skills' `metadata.version`, and the `instructions` say to read [AGENTS.md](https://set.world/AGENTS.md) first.
- **Methods.** `server/discover`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `skills/list` and `skills/get`, plus `initialize` and `ping` on the earlier revisions; `resources/templates/list` is always empty. Any other method is a JSON-RPC "method not found" error.

```ts
type SetApiInput = { path: string; query?: Record<string, unknown> };          // path: a GET path exactly as /api/spec lists it; query fills its ":name" segments
type SetSkillInput = { name: string };                                         // a skill slug, such as "rolling-an-item"
type DeriveSeedInput = { seed: number; index?: number; count?: number };       // seed 0 to 4294967295; index from 0 (default 0); count 1 to 256 (default 1)

type ToolResult = { content: [{ type: 'text'; text: string }]; isError?: true };
```

| Tool | Returns in `text` |
| --- | --- |
| `set_api` | The endpoint's own response body: JSON, CSV when `query` has `format: 'csv'`, or Markdown from `/api/skill` and `/api/guides/:guide`. The call goes through the endpoint itself, so its validation, its queue and its error envelope apply. `isError` is set when the endpoint answered with an error, when `path` or `query` is not valid, when a `:name` segment has no value in `query`, or when the endpoint did not answer within 60 seconds |
| `set_skill` | The skill's Markdown, as `/skills/<name>` serves it. `isError` is set for an unknown slug |
| `derive_seed` | `{ "seed": 7, "seeds": [{ "index": 0, "seed": 7 }, { "index": 1, "seed": 2654435776 }] }` for the input `{ "seed": 7, "count": 2 }`: `deriveSeed(seed, i)` for each `i` from `index` ([Rolling a group](https://set.world/skills/rolling-a-group)) |

**How `set_api` sends `query`.** A key named after a `:` segment of the path fills that segment and is not sent again: `{ "path": "/api/tables/:table", "query": { "table": "prefix", "q": "fier" } }` reads `/api/tables/prefix?q=fier`. Every other key becomes one parameter. An array of numbers is joined with dashes (`stats`, `rolls`, `indexes`, `attacker`, `defender`); any other object or array is sent as JSON (`override`, `actors`); `null` is left out; anything else is sent as text (`true`, `42`).

`path` must be written exactly as `/api/spec` lists it (`/api`, never `/api/roll`). The MCP endpoint itself and the page route `/roll/character` are not reachable through it.

**Resources.** `resources/list` lists every served skill with its `uri` (its URL: `https://set.world/AGENTS.md` for the guide, `https://set.world/skills/<name>` for every other skill), `name` (the frontmatter `name`), `title`, `description` and `mimeType: 'text/markdown'`. `resources/read` takes one of those URIs, or a skill's `skill://` URI, and returns the same Markdown as `set_skill`; an unknown URI is a JSON-RPC "resource not found" error (`-32602` on the stateless revision, `-32002` on the earlier ones).

**Skills.** `server/discover` declares the Skills extension (`io.modelcontextprotocol/skills`). `skills/list` returns one entry per served skill and `skills/get` returns one by its `uri`; an unknown URI is `-32602`. Read the file with `resources/read`.

```ts
type SkillEntry = {
  uri: string;                                       // "skill://set-rolling-an-item/SKILL.md": the frontmatter name, then SKILL.md
  frontmatter: { name: string; description: string; license: string; metadata: { version: string; title: string } };
  resources: [{ uri: string; digest: string; size: number }];   // the one file: its SHA-256 ("sha256:<hex>") and byte size, as served
};
type SkillsListResult = { skills: SkillEntry[] };
type SkillsGetResult = { skill: SkillEntry };
```

A call by hand on the stateless revision:

```sh
curl -s https://set.world/mcp -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/call' -H 'Mcp-Name: set_api' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"},"name":"set_api","arguments":{"path":"/api/roll/item","query":{"seed":7}}}}'
```

The response, with the item's JSON shortened:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "{\"name\":\"poor iron rope dart\",\"slot\":\"offhand\", …}" }],
    "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "set", "title": "Set", "version": "0.15.35" } }
  }
}
```

## What the API never does

It stores no wallets, inventories, levels or combat state, and has no second currency. The one write is the page route `/roll/character`, which saves an immutable birth certificate ([Rolling a character](https://set.world/skills/rolling-a-character)).
