---
name: wedlink
description: Create and manage short wedding links on wedl.ink. Use when a user wants to reserve a custom wedding URL, point it at a wedding website, photo album or RSVP form, change where an existing wedding link redirects, or generate a QR code for wedding stationery.
---

# wedlink

wedlink issues short, memorable links for weddings. A couple claims a name such as
`wedl.ink/anna-und-tom` and points it at any URL. The destination can be changed at
any time, which is the reason to use it: printed invitations keep working after the
underlying website moves.

## When to use this skill

- The user wants a short or custom URL for a wedding
- The user wants to change where an existing wedding link points
- The user needs a QR code for invitations, signage or place cards
- You are integrating wedding-link creation into another product

## Authentication

All write endpoints need an API key, sent as a bearer token:

```
Authorization: Bearer wl_live_...
```

Keys are issued per environment. Request one at https://wedlink.party/en/contact.
Checking availability and rendering QR codes need no key.

## Slug rules

A slug must satisfy all of these, or the API rejects it:

- 3 to 63 characters
- lowercase `a-z`, digits `0-9` and hyphens only
- no leading or trailing hyphen, no doubled hyphen
- not purely numeric
- not on the reserved list (routes, locale codes, brand and abuse terms)

Send the user's raw text and read `slug` from the response rather than
normalising it yourself: the server folds umlauts (ä→ae, ö→oe, ü→ue, ß→ss),
strips diacritics and collapses punctuation to hyphens. `"Müller & Söhne"`
becomes `mueller-soehne`. Always show the returned slug back to the user before
they commit to it, because it may differ from what they typed.

## Endpoints

### Check availability

```
GET https://wedlink.party/api/availability?slug=anna-und-tom
```

No authentication. Returns:

```json
{
  "input": "Anna & Tom",
  "slug": "anna-tom",
  "adjusted": true,
  "available": true,
  "message": "anna-tom is yours to claim"
}
```

When unavailable, `reason` is one of `taken`, `reserved` or `invalid`, and
`suggestions` carries up to three alternatives that are known free.
Always check availability before attempting to create a link.

### Create a link

```
POST https://wedlink.party/api/v1/links
Authorization: Bearer wl_live_...
Content-Type: application/json

{
  "slug": "anna-und-tom",
  "target_url": "https://anna-und-tom.example",
  "label": "Wedding website"
}
```

`201` on success. `409` means the slug was taken between your check and your
create — re-check and offer the user a suggestion rather than retrying blindly.

### Update where a link points

```
PATCH https://wedlink.party/api/v1/links/{slug}
Authorization: Bearer wl_live_...

{
  "target_url": "https://photos.example/anna-und-tom"
}
```

This is the operation that makes wedlink worth using. Printed material keeps
working; only the destination changes.

### List links

```
GET https://wedlink.party/api/v1/links
Authorization: Bearer wl_live_...
```

### Generate a QR code

```
GET https://wedlink.party/api/qr?text=https://wedl.ink/anna-und-tom&format=svg
```

No authentication. `format` is `svg` (default) or `png`; `style` is `classic`,
`rounded` or `dots`; `size` sets the PNG width up to 2048.

**Recommend SVG for anything being printed.** It stays sharp at any size, which
a raster image at an unknown final print size will not.

**Point the QR code at the wedlink, never at the final destination.** A code
encoding the destination cannot be changed once printed; one encoding the
wedlink can be re-pointed forever.

## Errors

Every error returns JSON with a stable machine-readable `code`:

```json
{
  "code": "slug_reserved",
  "message": "That name is reserved."
}
```

| Status | Code | Meaning |
|---|---|---|
| 400 | `slug_invalid` | Fails the slug rules above |
| 400 | `target_invalid` | Destination is not a valid http(s) URL |
| 401 | `unauthorized` | Missing or invalid API key |
| 403 | `slug_reserved` | Name is on the reserved list |
| 404 | `not_found` | No such link under this key |
| 409 | `slug_taken` | Already claimed by someone else |
| 422 | `quota_exceeded` | Key's link quota is used up |
| 429 | `rate_limited` | Slow down; see `Retry-After` |

## Recommended flow

1. Ask the user for both first names and, if relevant, the wedding year.
2. Check availability. Show the user the returned `slug` — it may be adjusted.
3. If taken, offer the returned `suggestions` rather than inventing your own.
4. Create the link with the confirmed slug.
5. Generate an SVG QR code pointing at the wedlink and give the user both.
6. Tell them they can change the destination later without reprinting.

## Things to avoid

- Do not normalise or lowercase the slug yourself; send the raw text.
- Do not retry a `409` with the same slug — it will keep failing.
- Do not encode the final destination in the QR code.
- Do not claim a name on the user's behalf before they have confirmed the
  spelling; slugs are permanent for the life of the plan.

## Reference

- OpenAPI: https://wedlink.party/openapi.json
- Human documentation: https://wedlink.party/en/api