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

# Look up a Discord account

> Read the linked Roblox account using the v2 lookup contract.

Use `GET /v2/discord` to look up a Roblox account linked to a Discord account.

## Request

Authenticate from your backend with a Dock API key. Supply the Discord ID as a string in the `discordId` query parameter.

```bash theme={null}
curl --request GET \
  --url "https://api.docksys.xyz/v2/discord?discordId=123456789012345678&guildId=987654321098765432" \
  --header "Authorization: Bearer ${DOCK_API_KEY}"
```

| Query parameter | Meaning |
| - | - |
| `discordId` | Required numeric Discord ID, represented as a string. |
| `guildId` | Server context for a guild-scoped key. Use the server your key is allowed to access. |
| `resolved` | Optional boolean. Defaults to `false`. Request additional provider profile details. Requires an eligible Premium key; it is not available to every key. |

A different `guildId` does not grant access to another server. Follow the scope assigned to your key.

## Response handling

Check the HTTP status. Successful v2 JSON responses contain `status`, `data`, `meta`, and `timestamp`. Treat Discord and Roblox IDs as strings.

A missing link returns `LINK_NOT_FOUND` with HTTP `404`. Invalid input, authentication failures, access restrictions, and rate limits are different failures; do not treat them as an unlinked account.

Provider profile details can be cached or unavailable. A username or avatar refresh does not create or change an account link.

See [authentication and scope](https://docs.docksys.xyz/api-reference/v2/authentication.md), [key security](https://docs.docksys.xyz/account/key-security.md), and the [migration checklist](https://docs.docksys.xyz/api-reference/v2/migration-checklist.md).


## OpenAPI

````yaml api/openapi-v2.json GET /v2/discord
openapi: 3.1.0
info:
  title: Dock API v2
  version: 2.0.0
  summary: >-
    Discord to Roblox verification, account linking, alt detection, API key
    management, and bot configuration.
  description: >-
    API v2 is the recommended Dock API for new integrations. It uses consistent
    response envelopes, stable error codes, request IDs, rate-limit metadata,
    and first-class bulk endpoints.


    Use the API only for legitimate verification, moderation, analytics, and
    automation workflows. Do not scrape, bypass rate limits, rotate keys or IPs
    to avoid limits, resell the service, or use detection outputs as definitive
    proof of wrongdoing. By using Dock, you agree to the Terms of Service and
    Privacy Policy.
  termsOfService: https://docksys.xyz/terms
  contact:
    name: Dock Support
    url: https://docksys.xyz/discord
  license:
    name: Dock Terms of Service
    url: https://docksys.xyz/terms
servers:
  - url: https://api.docksys.xyz
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Lookups
    description: >-
      Read account links, verification status, and Premium alt detection
      results.
  - name: Bulk
    description: Run ordered batch lookups with per-item results.
  - name: Verification Sessions
    description: Create hosted verification sessions and read completion state.
  - name: Writes
    description: Create, update, or delete account-link data in the current API-key scope.
externalDocs:
  description: Privacy Policy
  url: https://docksys.xyz/privacy
paths:
  /v2/discord:
    get:
      tags:
        - Lookups
      summary: Look up Roblox by Discord ID
      description: >-
        Returns the primary Roblox account linked to a Discord user.
        Guild-scoped API keys must provide `guildId`, and the Discord user must
        be in that guild. Set `resolved=true` only when you need expanded Roblox
        profile data; resolved profile data requires a Premium API key.
      operationId: getV2DiscordLookup
      parameters:
        - $ref: '#/components/parameters/DiscordIdQuery'
        - $ref: '#/components/parameters/GuildIdQuery'
        - $ref: '#/components/parameters/ResolvedQuery'
      responses:
        '200':
          description: Linked Roblox account found.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/V2SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DiscordLookup'
              example:
                status: 200
                data:
                  discordId: '123456789012345678'
                  robloxId: '156319135'
                  resolved:
                    roblox: null
                    discord: null
                meta:
                  requestId: req_9d7b8c6a5f4e
                  version: 2.0.0
                  rateLimit:
                    limit: 1
                    remaining: 0
                    resetAt: '2026-05-07T16:30:01.000Z'
                    retryAfter: null
                    scope: api_key
                  tier: free
                timestamp: '2026-05-07T16:30:00.000Z'
        '304':
          description: >-
            Matching If-None-Match returns 304 Not Modified with an empty body.
            Reuse your cached representation; do not parse JSON.
          headers:
            ETag:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    DiscordIdQuery:
      name: discordId
      in: query
      required: true
      description: Discord user ID.
      schema:
        type: string
        pattern: ^\d+$
        example: '123456789012345678'
    GuildIdQuery:
      name: guildId
      in: query
      required: false
      description: Discord guild ID. Required for guild-scoped API keys.
      schema:
        type: string
        pattern: ^\d{5,32}$
        example: '987654321098765432'
    ResolvedQuery:
      name: resolved
      in: query
      required: false
      description: >-
        Return expanded Discord or Roblox profile data. Requires Premium when
        true.
      schema:
        type: boolean
        default: false
  schemas:
    V2SuccessEnvelope:
      type: object
      required:
        - status
        - data
        - meta
        - timestamp
      properties:
        status:
          type: integer
          example: 200
        data:
          description: Endpoint-specific response payload.
          nullable: true
        meta:
          $ref: '#/components/schemas/V2Meta'
        timestamp:
          type: string
          format: date-time
    DiscordLookup:
      type: object
      required:
        - discordId
        - robloxId
        - resolved
      properties:
        discordId:
          type: string
        robloxId:
          type: string
        resolved:
          $ref: '#/components/schemas/ResolvedProfiles'
    V2Meta:
      type: object
      required:
        - requestId
        - version
        - rateLimit
      properties:
        requestId:
          type: string
          example: req_9d7b8c6a5f4e
        version:
          type: string
          example: 2.0.0
        rateLimit:
          $ref: '#/components/schemas/RateLimitMeta'
        tier:
          type: string
          enum:
            - free
            - premium
          description: Present on API-key authenticated developer endpoints.
      additionalProperties: true
    ResolvedProfiles:
      type: object
      properties:
        roblox:
          nullable: true
          description: Expanded Roblox profile when requested and available.
          additionalProperties: true
        discord:
          nullable: true
          description: >-
            Expanded Discord profile or array of profiles when requested and
            available.
          additionalProperties: true
    V2ErrorEnvelope:
      type: object
      required:
        - status
        - error
        - meta
        - timestamp
      properties:
        status:
          type: integer
          example: 429
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              example: RATE_LIMITED
            message:
              type: string
              example: Too many requests. Please retry after 1 seconds.
            details:
              nullable: true
              additionalProperties: true
        meta:
          $ref: '#/components/schemas/V2Meta'
        timestamp:
          type: string
          format: date-time
    RateLimitMeta:
      type: object
      required:
        - limit
        - remaining
        - resetAt
        - retryAfter
        - scope
      properties:
        limit:
          type: integer
          nullable: true
        remaining:
          type: integer
          nullable: true
        resetAt:
          type: string
          format: date-time
          nullable: true
        retryAfter:
          type: integer
          nullable: true
        scope:
          type: string
          nullable: true
          example: api_key
        bucket:
          type: string
          nullable: true
          example: sessions_create
  responses:
    BadRequest:
      description: The request is missing required input or contains invalid input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
    Unauthorized:
      description: The API key is missing, invalid, expired, revoked, or suspended.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
          example:
            status: 401
            error:
              code: INVALID_API_KEY
              message: Invalid API key.
              details: null
            meta:
              requestId: req_9d7b8c6a5f4e
              version: 2.0.0
              rateLimit:
                limit: null
                remaining: null
                resetAt: null
                retryAfter: null
                scope: null
            timestamp: '2026-05-07T16:30:00.000Z'
    Forbidden:
      description: >-
        The authenticated key or session does not have access to the requested
        resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
    NotFound:
      description: >-
        The requested link, session, key, config item, or guild resource was not
        found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
    RateLimited:
      description: >-
        Too many requests. Back off and retry after the `Retry-After` header or
        `meta.rateLimit.retryAfter` value.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Current short-window pacing limit.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in the short-window bucket.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the short-window bucket resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
    InternalError:
      description: Dock could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Dock API key. Send `Authorization: Bearer <api key>`.'

````

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