# Remove a path alias (Developers)

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

Removes one of the code's path aliases: the old path stops opening the code, and another code on the domain can take it.

The response is `{ "data": { "id", "deleted": true } }`. An alias the code doesn't have is a `404`.

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

## DELETE /codes/{id}/aliases/{aliasId}

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

**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` |
| `aliasId` | string | Yes | The path alias's `id`. 1–64 characters. Example: `cm5alias0old0flyer0link01` |

### Responses

#### 200

Removed

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | Yes |  |
| `data.id` | string | Yes |  |
| `data.deleted` | true | Yes |  |

```json
{
  "data": {
    "id": "cm5alias0old0flyer0link01",
    "deleted": true
  }
}
```

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

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

#### 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 DELETE "https://api.qrdx.dev/v1/codes/cm5code0spring0menu00001/aliases/cm5alias0old0flyer0link01" \
  -H "Authorization: Bearer $QRDX_API_KEY"
```
