# 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

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

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