# List path aliases (Developers)

URL: https://qrdx.dev/docs/developers/api/list-code-aliases
Source: https://github.com/qrdxinc/qrdx/blob/main/apps/docs/content/docs/developers/api/list-code-aliases.mdx

The old paths on a code's custom domain that also open the code, oldest first.

A path alias keeps codes printed with another provider's links working after your domain moves to QRdx: `go.example.com/r/abc` opens the code as its own short link does, with its scans, password, schedule, scan limit and pause. Aliases belong to the code's current domain, so a code on QRdx's own domain has none (`NO_CUSTOM_DOMAIN`). More in [Path aliases](https://qrdx.dev/docs/migrate#path-aliases).

**Scope:** `codes:read` or `codes:write`, for API keys and OAuth tokens alike.

## GET /codes/{id}/aliases

`GET https://api.qrdx.dev/v1/codes/{id}/aliases`

**Auth:** an API key or an OAuth 2.0 access token, sent as `Authorization: Bearer <key or token>`, with the scope `codes:read` or `codes:write`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The code's `id`. 1–64 characters. Example: `cm5code0spring0menu00001` |

### Responses

#### 200

The code's path aliases

Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | PathAlias[] | Yes | Oldest first |
| `data[].id` | string | Yes | Path alias id |
| `data[].path` | string | Yes | The old path, exact and case-sensitive, such as `/r/abc`; the query string never counts |
| `data[].url` | string (uri) | Yes | The old link: the code's custom domain and the path |
| `data[].createdAt` | string (date-time) | Yes | When the alias was added (ISO 8601, UTC) |

```json
{
  "data": [
    {
      "id": "cm5alias0old0flyer0link01",
      "path": "/r/abc",
      "url": "https://go.example.com/r/abc",
      "createdAt": "2026-01-05T09:30:00.000Z"
    }
  ]
}
```

#### 400

`VALIDATION_ERROR`: The body, query or path failed validation. `data.details` lists each problem as `{ path, message }` (`{ param, message }` on the image API), with the row's `index` when the body is an array of codes.

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "status": 400,
  "data": {
    "details": [
      {
        "path": "destinationUrl",
        "message": "Enter a full URL, starting with https://"
      }
    ]
  }
}
```

#### 401

`UNAUTHORIZED`: No credentials: the request has no `Authorization: Bearer` header (and no QRdx browser session).

`INVALID_TOKEN`: The API key or access token is unknown, revoked or expired (access tokens last one hour), or the key's creator was banned or left the key's workspace.

Headers: `WWW-Authenticate`.

```json
{
  "code": "UNAUTHORIZED",
  "message": "Missing API key. Send an API key as \"Authorization: Bearer <key>\"; create one at https://qrdx.dev/dashboard?to=settings/developers. OAuth access tokens go in the same header.",
  "status": 401,
  "docs": "https://qrdx.dev/docs/developers/api-keys"
}
```

#### 403

`INSUFFICIENT_SCOPE`: The API key or token is valid but lacks the scope this endpoint needs.

```json
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key needs the 'codes:read' scope. Create a key that includes it at https://qrdx.dev/dashboard?to=settings/developers; a key's scopes can't be changed.",
  "status": 403,
  "docs": "https://qrdx.dev/docs/developers/api-keys"
}
```

#### 404

`NOT_FOUND`: No such endpoint, or the code, hook, theme, custom domain or path alias doesn't exist in the workspace the key or token acts on.

```json
{
  "code": "NOT_FOUND",
  "message": "QR code not found",
  "status": 404
}
```

#### 409

`NO_CUSTOM_DOMAIN`: Path aliases are for codes on a custom domain, and this code is on QRdx's own.

```json
{
  "code": "NO_CUSTOM_DOMAIN",
  "message": "Path aliases are for codes on a custom domain, and this code is on QRdx's own.",
  "status": 409
}
```

#### 429

`RATE_LIMITED`: Too many requests: a per-minute limit (only `Retry-After` is set) or the workspace's daily quota (`Retry-After` plus `X-RateLimit-*`).

Headers: `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

```json
{
  "code": "RATE_LIMITED",
  "message": "Daily API limit reached: the Free plan allows 1,000 requests a day. It resets at 00:00 UTC. Upgrade your plan for a higher limit.",
  "status": 429
}
```

#### 500

`INTERNAL_ERROR`: Something failed on QRdx's side. It has been logged.

```json
{
  "code": "INTERNAL_ERROR",
  "message": "Something failed on QRdx's side. It has been logged.",
  "status": 500
}
```

#### 503

`PATH_ALIASES_UNAVAILABLE`: Path aliases aren't available on this deployment yet: its database doesn't have their table (a self-hosted instance that hasn't applied `packages/database/manual-sql/2026-11-18-path-aliases.sql`).

```json
{
  "code": "PATH_ALIASES_UNAVAILABLE",
  "message": "Path aliases aren't available on this deployment yet: its database doesn't have their table (a self-hosted instance that hasn't applied packages/database/manual-sql/2026-11-18-path-aliases.sql).",
  "status": 503
}
```

### Example

```bash title="Terminal"
curl "https://api.qrdx.dev/v1/codes/cm5code0spring0menu00001/aliases" \
  -H "Authorization: Bearer $QRDX_API_KEY"
```
