# Musael public API

The public API generates seeded names using the existing deterministic generators. It is free and requires no account or API key. It does not use AI or access private manuscripts or projects. Contract details are in the [OpenAPI document](https://musael.com/docs/openapi.json).

## Seeded names

`GET https://musael.com/api/public/v1/names`

Optional query parameters:

| Name | Default | Allowed values |
| --- | --- | --- |
| `kind` | `fantasy` | `fantasy`, `fantasy-last`, `elf`, `dwarf`, `dragon`, `kingdom`, `town`, `village`, `tavern`, `wizard`, `orc`, `city`, `guild`, `ship`, `sword`, `spell`, `god`, `demon`, `vampire`, `pirate`, `knight`, `sci-fi-planet`, `alien`, `starship` |
| `seed` | `1` | Integer from 1 through 999999 |
| `count` | `10` | Integer from 1 through 20 |

The response contains `version: "1"`, the selected `kind` and `seed`, generated `names`, and a source URL. Results are deterministic for a given generator data and seed; a future release may change generator data or behavior.

```sh
curl 'https://musael.com/api/public/v1/names?kind=elf&seed=42&count=3'
```

## Request, limits, and privacy

Use HTTPS. Successful responses have `version: "1"`; error responses contain an `error` object with a stable `code` and displayable `message`. URLs over 1,024 characters are rejected. The API is free, has no availability or throughput guarantee, and requires no login, key, subscription, or paid tier.

This API uses the site's per-client and per-runtime rate limits. Honor `Retry-After` on `429` or `503`, use bounded retries with backoff, and do not change IP addresses, proxies, or accounts to evade a quota. Do not automatically retry validation errors.

Only send the documented parameters. This endpoint performs name generation; it does not use AI, access an account, or read private manuscripts or projects. The separate workspace MCP server is a different service with explicit writer authorization and project scopes.