Writes

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

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

PATCH /v2/discord

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

string

required

Existing Discord user ID on the stored link.

string

required

New Discord user ID to store on the link.

string

Required for scoped keys.

cURL

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"
  }'

200 OK

{
  "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

PATCH /v2/roblox

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

string

required

Discord user ID to create or update.

string

required

Roblox user ID to attach to the Discord user.

string

Required for scoped keys.

200 OK

{
  "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

DELETE /v2/roblox

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

string

required

Discord user ID whose Roblox link should be removed.

string

Required for scoped keys.

200 OK

{
  "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

DELETE /v2/data

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

boolean

required

Must be true. This guard prevents accidental deletes.

cURL

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

200 OK

{
  "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.

Start Here

API Reference

Update a Discord ID

Create or update a Roblox link

Remove a Roblox link

Delete scoped data

Cache behavior

Failure cases

​Update a Discord ID

​Create or update a Roblox link

​Remove a Roblox link

​Delete scoped data

​Cache behavior

​Failure cases

Update a Discord ID

Create or update a Roblox link

Remove a Roblox link

Delete scoped data

Cache behavior

Failure cases