---
title: "Create or join a team world by name"
method: POST
path: "/api/keys"
tags: ["Team"]
---

# Create or join a team world by name

`POST /api/keys`

## Request

- Base URL: `https://sim.animahealth.com`
- URL: `https://sim.animahealth.com/api/keys`
- Auth: none required

Creates or joins a persistent world using a lowercase name with all whitespace removed. Anyone who knows the name can join its simulation world. Repeat requests return the same reusable key and world. Older hash-only teams receive a reusable key for their existing world; previous keys remain valid. Ambiguous historical names spanning multiple worlds return 409: use an existing key. Up to 5,000 distinct team worlds; existing teams can rejoin at capacity. No per-IP or time-based throttle. Omit site to create a team with all participant scopes. Rejoining preserves existing scopes. Legacy has no API key scope.

## Request body

- object
  - `teamName` string, required: Lowercased with all whitespace removed before validation. The normalised name must contain 2–80 characters.
  - `site` 'gp' | 'hospital' | 'community' | 'pharmacy' | 'diagnostics' | 'referrals' | 'wearables'

## Response `201`

Team created or joined; copy apiKey

- Key
  - `apiKey` string, required: Reusable team key. Joining with the same normalised name returns this key again.
  - `team` string, required: Team attribution label; older teams retain their original label.
  - `teamName` string, required: Canonical join name: lowercase with all whitespace removed.
  - `world` string, required
  - `scopes` string[], required
  - `created` boolean, required: True only when this request created a new world.

## Other responses

- `400`: Invalid input or unsupported workflow
- `401`: Missing or invalid credentials
- `403`: Scope, origin or operator restriction
- `404`: Unknown resource
- `409`: Stale version, invalid transition or unavailable capacity
- `413`: Request exceeds this operation's body-size limit
- `429`: Deployment has reached its 5,000-team capacity
- `500`: Internal simulation error
- `501`: Legacy is browser-only

---

[API](https://skmtc.dev/animahealth/apis/nhs-sim-api.md) - [All operations](https://skmtc.dev/animahealth/apis/nhs-sim-api/llms.txt) - [OpenAPI document](https://skmtc.dev/animahealth/apis/nhs-sim-api/revisions/c7803d7a3e58?raw)