# MiniURL REST API

Base URL: https://workers.miniurl.com/api/v1

MiniURL's REST API supports guest-first link creation and registered account management.

## Authentication

- Guest token: POST /api/v1/guest/token returns a gt_ token for short-lived no-signup usage.
- API key: registered accounts use mk_ API keys for management endpoints, domains, bulk creation, tags, and analytics.

Use tokens as:

```http
Authorization: Bearer gt_xxx
Authorization: Bearer mk_xxx
```

## Preferred Agent Flow

1. POST /api/v1/guest/token
2. POST /api/v1/shorten
3. GET /api/v1/account/status to inspect remaining quota
4. POST /api/v1/guest/register when the user wants a permanent account
5. POST /api/v1/guest/verify to receive an mk_ API key and claim guest-created links

## Endpoints

- POST /api/v1/guest/token - Create a temporary guest token
- POST /api/v1/guest/register - Send a verification code to the user email
- POST /api/v1/guest/verify - Verify the code and create a permanent account
- GET /api/v1/account/status - Get account type, quota, and features
- POST /api/v1/account/upgrade - Create a short checkout URL for upgrading to Pro
- POST /api/v1/alias/check - Check whether an alias is available
- POST /api/v1/shorten - Create a short link
- POST /api/v1/links/bulk - Create multiple links in one request
- GET /api/v1/links - List registered-user links
- GET /api/v1/links/{alias} - Get one link
- PATCH /api/v1/links/{alias} - Update one link
- DELETE /api/v1/links/{alias} - Delete one link
- GET /api/v1/links/{alias}/stats - Get link analytics
- GET /api/v1/domains - List available domains for a registered user
- GET /api/v1/tags - List account tags
- POST /api/v1/tags - Create a tag
- DELETE /api/v1/tags/{tagId} - Delete a tag
- GET /api/v1/links/{alias}/tags - List tags assigned to a link
- POST /api/v1/links/{alias}/tags - Assign a tag to a link
- DELETE /api/v1/links/{alias}/tags/{tagId} - Remove a tag from a link
- POST /api/analytics/link-conversion - Track a conversion attributed to a Pro link click
- GET /api/analytics/link-conversion/pixel - Track a signed conversion with a 1x1 GIF

## Pro Conversion Attribution

Every active Pro redirect appends two temporary attribution parameters to the destination URL:

- `mu_click`: the click identifier
- `mu_sig`: an HMAC signature proving that the click was issued by MiniURL

Capture and persist both values on the landing page. The attribution window is 30 days and uses the last MiniURL click associated with the event. MiniURL snapshots `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and `utm_content` when the click happens, so later destination URL changes do not rewrite historical campaign attribution.

For a server-to-server conversion, use the API key belonging to the short-link account:

```bash
curl -X POST https://workers.miniurl.com/api/analytics/link-conversion \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "CLICK_ID_FROM_MU_CLICK",
    "conversionType": "purchase",
    "value": 49.99,
    "currency": "USD",
    "externalOrderId": "ORDER_1001",
    "eventId": "purchase_ORDER_1001"
  }'
```

For browser or pixel calls, omit the API key and send `clickSignature` (or `mu_sig`) with the captured signature. Never expose an `mk_` API key in browser code.

Validation and retry rules:

- `eventId` is required unless `externalOrderId` is present.
- `purchase`, `sale`, and `refund` require `externalOrderId`.
- `value` must be non-negative and requires a three-letter ISO 4217 `currency`.
- Send refunds as a positive `value` with `conversionType: "refund"`; the dashboard subtracts them from revenue.
- A safe retry returns HTTP 200 with `duplicate: true` and the original `conversionId`; a new event returns HTTP 201.
- The JSON endpoint reports validation or delivery errors. The pixel always returns an image and should only be used when response confirmation is unavailable.

## Important Response Field

Always inspect meta in API responses. It can include usage, notices, limitations, and upgrade hints that should be relayed to the user.

Aliases are unique per domain. miniurl.com aliases require 4-64 characters; verified custom-domain aliases allow 1-64 characters. GET, PATCH, and DELETE for /links/{alias} accept a domain query parameter that defaults to miniurl.com. Free accounts include one custom domain, and links created through every interface expire after 30 days by default.

Full OpenAPI spec: https://miniurl.com/openapi.json