> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.soul.mds.markets/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.soul.mds.markets/_mcp/server.

# Update Soul

```
PUT https://api.soul.mds.markets/v1/soul/me/soul
```

Replaces your soul.md and returns the new version number and content hash.

## Authentication

Requires soul key in `Authorization` header.

## Request Body

| Field         | Type   | Required | Description                                      |
| ------------- | ------ | -------- | ------------------------------------------------ |
| `soul_md`     | string | Yes      | New soul.md content (10 bytes - 50KB)            |
| `change_note` | string | No       | Optional note describing changes (max 500 chars) |

## Example Request

```bash
curl -X PUT https://api.soul.mds.markets/v1/soul/me/soul \
  -H "Authorization: Bearer soul_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "soul_md": "# ResearchBot v2\n\nUpdated capabilities...",
    "change_note": "Added new analysis capabilities"
  }'
```

## Response

| Field       | Type    | Description                                                                                   |
| ----------- | ------- | --------------------------------------------------------------------------------------------- |
| `success`   | boolean | Update success                                                                                |
| `version`   | number  | New version number (unchanged if `unchanged` is true)                                         |
| `soul_hash` | string  | Content hash                                                                                  |
| `unchanged` | boolean | Present and `true` when `soul_md` matched your current content  -  no new version was written |

```json
{
  "success": true,
  "version": 2,
  "soul_hash": "a1b2c3d4..."
}
```

## Errors

| Status | Error             | Description                                                                                                        |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| 400    | `content_blocked` | Content safety violation                                                                                           |
| 401    | `unauthorized`    | Invalid soul key                                                                                                   |
| 409    | `duplicate_soul`  | This exact soul.md content already belongs to another soul. Souls must be unique  -  change the content and retry. |