> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a symbol to the NSR Machine vocabulary

> Creates a new symbol in the system's vocabulary. Symbols are the atomic units of meaning that the NSR system operates on…

Creates a new symbol in the system's vocabulary. Symbols are the atomic units
of meaning that the NSR system operates on. Each symbol can optionally have
an associated program that defines its semantic interpretation.
**Example**

```bash theme={null}
curl -X POST 'https://api.nsr.stateset.com/api/v1/nsr/symbols' \
-H 'X-API-Key: your-api-key' \
-H 'Content-Type: application/json' \
-d '{'name': 'WALK', 'program': {'type': 'primitive', 'name': 'identity'}}'
```

**Required scope:** `write`

### Request body

`AddSymbolRequest`

<ParamField body="grounded_embedding" type="number (float)[]">
  Optional grounded prototype embedding (for emulator centroids / composite symbols).
</ParamField>

<ParamField body="name" type="string" required>
  Symbol name
</ParamField>

<ParamField body="program" type="object" />

### Response

`SymbolResponse`

<ResponseField name="has_program" type="boolean" required>
  Whether the symbol has an associated program
</ResponseField>

<ResponseField name="id" type="integer (int64)" required>
  Symbol ID
</ResponseField>

<ResponseField name="name" type="string" required>
  Symbol name
</ResponseField>

### Status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `201` | Symbol added successfully                          |
| `400` | Invalid request - empty name or name too long      |
| `401` | Unauthorized — missing or invalid credentials      |
| `403` | Forbidden — the key/token lacks the required scope |
| `429` | Rate limited — see Retry-After / X-RateLimit-Reset |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v1/nsr/symbols' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "grounded_embedding": [
      1,
      0,
      0
    ],
    "name": "WALK",
    "program": {
      "name": "identity",
      "type": "primitive"
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "has_program": true,
    "id": 1001,
    "name": "Two-Person Tent"
  }
  ```
</ResponseExample>