> ## Documentation Index
> Fetch the complete documentation index at: https://docksystems.mintlify.site/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.

## 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.

**oldDiscordId** `string` *required*

Existing Discord user ID on the stored link.

**newDiscordId** `string` *required*

New Discord user ID to store on the link.

**guildId** `string`

Required for scoped keys.

```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.

**discordId** `string` *required*

Discord user ID to create or update.

**robloxId** `string` *required*

Roblox user ID to attach to the Discord user.

**guildId** `string`

Required for scoped keys.

```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.

**discordId** `string` *required*

Discord user ID whose Roblox link should be removed.

**guildId** `string`

Required for scoped keys.

```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.

**confirm** `boolean` *required*

Must be `true`. This guard prevents accidental deletes.

```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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.