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

# Writes

> Update Discord IDs, update Roblox links, remove Roblox links, and delete scoped data with v2.

Write endpoints change data in the authenticated API key's scope. They require API-key authentication and a JSON body.

<Warning>
  Scoped keys must provide `guildId` for writes. Dock checks that the bot is in the guild and that the affected Discord user is a member of the guild.
</Warning>

## Update a Discord ID

```http theme={null}
PATCH /v2/discord
```

Use this when a stored link needs to move from one Discord ID to another.

<ParamField body="oldDiscordId" type="string" required>
  Existing Discord user ID on the stored link.
</ParamField>

<ParamField body="newDiscordId" type="string" required>
  New Discord user ID to store on the link.
</ParamField>

<ParamField body="guildId" type="string">
  Required for scoped keys.
</ParamField>

```bash cURL theme={null}
curl --request PATCH \
  --url "https://api.docksys.xyz/v2/discord" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "oldDiscordId": "123456789012345678",
    "newDiscordId": "222222222222222222",
    "guildId": "987654321098765432"
  }'
```

```json 200 OK theme={null}
{
  "status": 200,
  "data": {
    "previousDiscordId": "123456789012345678",
    "discordId": "222222222222222222",
    "robloxId": "156319135",
    "updated": true
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0"
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Create or update a Roblox link

```http theme={null}
PATCH /v2/roblox
```

Use this when a Discord user should point to a Roblox account. Dock verifies that the Roblox user exists before saving.

<ParamField body="discordId" type="string" required>
  Discord user ID to create or update.
</ParamField>

<ParamField body="robloxId" type="string" required>
  Roblox user ID to attach to the Discord user.
</ParamField>

<ParamField body="guildId" type="string">
  Required for scoped keys.
</ParamField>

```json 200 OK theme={null}
{
  "status": 200,
  "data": {
    "discordId": "123456789012345678",
    "robloxId": "156319135",
    "previousRobloxId": null,
    "updated": true
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0"
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Remove a Roblox link

```http theme={null}
DELETE /v2/roblox
```

Use this to remove the Roblox account from a Discord user while leaving the user record available for future updates.

<ParamField body="discordId" type="string" required>
  Discord user ID whose Roblox link should be removed.
</ParamField>

<ParamField body="guildId" type="string">
  Required for scoped keys.
</ParamField>

```json 200 OK theme={null}
{
  "status": 200,
  "data": {
    "discordId": "123456789012345678",
    "removedRobloxId": "156319135",
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0"
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Delete scoped data

```http theme={null}
DELETE /v2/data
```

Use this only when you need to clear all link records in the current key's data scope.

<ParamField body="confirm" type="boolean" required>
  Must be `true`. This guard prevents accidental deletes.
</ParamField>

```bash cURL theme={null}
curl --request DELETE \
  --url "https://api.docksys.xyz/v2/data" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"confirm":true}'
```

```json 200 OK theme={null}
{
  "status": 200,
  "data": {
    "deletedRecords": 42,
    "scope": "pid",
    "pid": "PID-ABC12345",
    "collection": "data_pid_abc12345"
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0"
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Cache behavior

v2 invalidates affected lookup caches after writes. That includes related Discord IDs, Roblox IDs, PID-scoped data, and shared lookup entries.

## Failure cases

| Code                | When it happens                                                      |
| ------------------- | -------------------------------------------------------------------- |
| `MISSING_PARAMETER` | Required IDs or `guildId` are missing.                               |
| `INVALID_PARAMETER` | An ID has the wrong format or Roblox could not verify it.            |
| `FORBIDDEN`         | Dock is not in the guild, or the Discord user is not a guild member. |
| `LINK_NOT_FOUND`    | The requested link does not exist.                                   |
| `INVALID_BODY`      | `confirm` is missing or not `true` for destructive deletes.          |