# Add a path alias (Developers)

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

Makes an old path on the code's custom domain open the code, so codes printed with that link keep working.

Send the path after the domain (`/r/abc`) or the whole old link on the code's domain. The rules are the dashboard's, with its reasons as the error messages:

- The code has to be on a verified custom domain of the workspace, with custom domains on the plan (Pro and Business).
- The path matches exactly and capitals count. The query string and a `/` at the end are dropped.
- At most 200 characters and 8 parts separated by `/`, each made of letters, digits, `-`, `_`, `.` and `~`.
- A path that fits a back-half (one part of 3 to 64 letters, digits, `-` or `_`) can't be an alias: give the code that back-half instead.
- QRdx keeps `/api/…`, `/stats/…`, `/q/…`, GS1 Digital Links (`/01/…`) and files such as `/robots.txt` for itself.
- On a domain, each path opens one code. `/p/<x>` is refused while a code there has the back-half x, because its hosted page answers at that path.
- A code can have up to 5 path aliases.

A new alias is a `201`. A path the code already has returns that alias with a `200`. A domain's first alias can take a minute to start answering.

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

## POST /codes/{id}/aliases

`POST 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:write`.

### Path parameters

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

### Request body

`application/json`, required. An old path on the code's custom domain

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | string | Yes | The old path on the code's custom domain, such as `/r/abc`, or the whole old link on that domain (`https://go.example.com/r/abc`). The query string and a `/` at the end are dropped.. up to 2048 characters |

```json title="A path"
{
  "path": "/r/abc"
}
```

```json title="The whole old link"
{
  "path": "https://go.example.com/r/abc"
}
```

### Responses

#### 200

The code already had this path: its alias

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | PathAlias | Yes | An old path on a code's custom domain that also opens the code |
| `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"
  }
}
```

#### 201

Added

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | PathAlias | Yes | An old path on a code's custom domain that also opens the code |
| `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.

`INVALID_PATH_ALIAS`: The path can't be a path alias: it's empty, too long, has too many parts or characters QRdx doesn't allow, fits a back-half, is a path QRdx uses on custom domains, or is a link on another domain. `data.reason` says which (`empty`, `length`, `segments`, `characters`, `backHalf`, `reserved`, `otherDomain`).

`DOMAIN_NOT_VERIFIED`: `domainId` points to a custom domain that isn't verified yet, or a path alias was added to a code whose domain isn't verified yet.

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

#### 402

`PLAN_REQUIRED`: The feature isn't on the workspace's plan: bulk creation, custom back-halves and custom domains (with their path aliases) need Pro; conversions and hooks need Business.

```json
{
  "code": "PLAN_REQUIRED",
  "message": "The feature isn't on the workspace's plan: bulk creation, custom back-halves and custom domains (with their path aliases) need Pro; conversions and hooks need Business.",
  "status": 402
}
```

#### 403

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

`FORBIDDEN`: The caller may not do this: a workspace member deleting a code someone else created, a member managing hooks, a browser-session write from another site, or pointing a code QRdx switched off after a review anywhere new (a new destination, or another type). An API key can do only what its creator's role in its workspace allows.

```json
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key needs the 'codes:write' 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.

`PATH_ALIAS_TAKEN`: Another code on the domain already answers at that path: its path alias (`data.reason` `taken`), or, for `/p/<x>`, its hosted page, because it has the back-half x (`hostedPage`).

`PATH_ALIAS_LIMIT`: The code already has as many path aliases as a code can have on its domain (5).

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

#### 413

`PAYLOAD_TOO_LARGE`: The body is over the endpoint's limit: 4 MB for codes, 16 KB for hooks and path aliases, 8 KB for conversions. Also a batch of codes whose response (each code with its design) would be over 4 MB; nothing is created.

```json
{
  "code": "PAYLOAD_TOO_LARGE",
  "message": "The body is over the endpoint's limit: 4 MB for codes, 16 KB for hooks and path aliases, 8 KB for conversions. Also a batch of codes whose response (each code with its design) would be over 4 MB; nothing is created.",
  "status": 413
}
```

#### 415

`UNSUPPORTED_MEDIA_TYPE`: A write without `Content-Type: application/json`.

```json
{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "A write without Content-Type: application/json.",
  "status": 415
}
```

#### 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 -X POST "https://api.qrdx.dev/v1/codes/cm5code0spring0menu00001/aliases" \
  -H "Authorization: Bearer $QRDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/r/abc"}'
```
