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

# Overview

> Understand the v2 response envelope, endpoint families, errors, versioning, and migration path from v1.

API v2 is the recommended Dock API for new projects. It keeps the same core product model as v1 while improving consistency, bulk behavior, caching, error handling, and response metadata.

## Endpoint families

> **Lookups**
>
> Resolve Discord IDs, Roblox IDs, verification status, and Premium alt detection.

> **Bulk lookups**
>
> Send arrays of IDs and receive ordered per-item results.

> **Verification sessions**
>
> Create sessions, redirect users, and read completion by polling or SSE.

> **Writes**
>
> Update links, remove links, and delete data in your API-key scope.

## Response envelope

Every v2 JSON response uses one shape.

**Success**

```json theme={null}
{
  "status": 200,
  "data": {
    "discordId": "123456789012345678",
    "robloxId": "156319135",
    "resolved": {
      "roblox": null,
      "discord": null
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0",
    "rateLimit": {
      "limit": 1,
      "remaining": 0,
      "resetAt": "2026-05-07T00:00:01.000Z",
      "retryAfter": null,
      "scope": "api_key",
      "bucket": "second"
    },
    "tier": "free"
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

**Error**

```json theme={null}
{
  "status": 404,
  "error": {
    "code": "LINK_NOT_FOUND",
    "message": "No linked Roblox account was found for that Discord ID.",
    "details": null
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0",
    "rateLimit": {
      "limit": 1,
      "remaining": 0,
      "resetAt": "2026-05-07T00:00:01.000Z",
      "retryAfter": null,
      "scope": "api_key",
      "bucket": "second"
    }
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Envelope fields

**status** `number` *required*

HTTP status code mirrored in the response body.

**data** `object | array | null`

Successful response payload. Present when the request succeeds.

**error.code** `string`

Stable machine-readable error code. Present when the request fails.

**error.message** `string`

Human-readable error message safe to log or show in developer tooling.

**meta.requestId** `string` *required*

Request ID for support, logs, and debugging.

**meta.version** `string` *required*

v2 implementation version. Current value is `2.0.0`.

**meta.rateLimit** `object` *required*

Active rate-limit context when available.

**timestamp** `string` *required*

ISO 8601 timestamp generated by Dock.

## Common error codes

| Code | Meaning |
| - | - |
| `BAD_REQUEST` | The request could not be parsed or understood. |
| `MISSING_PARAMETER` | A required query, path, or body value is missing. |
| `INVALID_PARAMETER` | A supplied value has the wrong format. |
| `INVALID_BODY` | The JSON body is missing or invalid. |
| `INVALID_API_KEY` | The API key is missing, invalid, expired, or revoked. |
| `INVALID_SESSION` | The dashboard session is missing or expired. |
| `FORBIDDEN` | The key or session does not have access. |
| `PREMIUM_REQUIRED` | Premium access is required. |
| `LINK_NOT_FOUND` | No matching account link exists. |
| `SESSION_NOT_FOUND` | The verification session does not exist for this key. |
| `SESSION_EXPIRED` | The verification session expired. |
| `RATE_LIMITED` | The key or route is temporarily limited. |
| `SHARED_IP_RATE_LIMITED` | Shared IP or origin abuse protection limited the request. |
| `BULK_LIMIT_EXCEEDED` | The request exceeded a bulk input limit. |
| `CONFLICT` | The request conflicts with existing state. |
| `INTERNAL_ERROR` | Dock could not complete the request. |

## Versioning

Use the URL version for API routing:

```text theme={null}
/v2/discord
/v2/roblox
/v2/sessions
```

Dock also supports a dated contract header for compatible routes:

```http theme={null}
Dock-Version: 2026-01-01
```

If the header is omitted, Dock currently defaults to `2026-01-01`.

## v1 migration notes

> **Responses**
>
> v1 returns route-specific response shapes. v2 always returns `status`, `data` or `error`, `meta`, and `timestamp`.

> **Errors**
>
> v1 error messages can vary by route. v2 uses stable error codes for client
> logic.

> **Resolved data**
>
> v2 makes `resolved` explicit and defaults it to `false`. Request
> `resolved=true` only when you need expanded profiles.

> **Bulk**
>
> v2 bulk endpoints use `POST` bodies, preserve input order, and return per-item errors instead of failing the whole request for missing links.

> [!NOTE]
>
> v1 remains available for existing integrations. New work should use v2 unless
> you are maintaining an older client.


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