> ## Documentation Index
> Fetch the complete documentation index at: https://docs.u301.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shorten Link

> Shorten a long link

<Note>
  This API DOES NOT require authorization, which means using an anonymous account.
</Note>

This API converts long URLs into short URLs.

If the same long URL has already been shortened in the same account, it will return the previously shortened URL.

## Example #1: Shorten google.com

You can short `google.com` by request API URL: `https://api.u301.com/v2/shorten?url=https://google.com`,
even if visit the URL directly in the browser.

## Example #2: Specify Domain

We assume you have already added your own domain `go.example.com`, you can shorten your link by request API:

`https://api.u301.com/v2/shorten?domain=go.example.com&url=https://google.com`

Which specifies the domain in the query string, and that will override the default domain.

## Example #3: Custom Alias

We'd like to create a shortened link `u301.co/dashboard` which point to u301 dashboard.\
Request with a parameter `slug`:\
`https://api.u301.com/v2/shorten?url=https://u301.com/dashboard/&slug=dashboard`

the returned result is

```json theme={null}
{
  "hostname": "u301.com",
  "url": "https://u301.com/dashboard/",
  "code": "cZ",
  "tally": 216,
  "status": "public",
  "slug": "dashboard",
  "urlPrefix": "https://u301.co",
  "domain": "u301.co",
  "shortened": "https://u301.co/dashboard"
}
```

You can see the link in field `shortened` is `https://u301.co/dashboard` 🎉


## OpenAPI

````yaml GET /shorten
openapi: 3.0.1
info:
  title: U301 OpenAPI
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.u301.com/v2
security: []
paths:
  /shorten:
    get:
      description: Shorten link
      parameters:
        - name: url
          in: query
          description: >-
            The long URL to shorten. the URL MUST starts with a valid schema,
            such as `http://` or `https://`
          schema:
            type: string
          required: true
        - name: title
          in: query
          description: The title of the link
          schema:
            type: string
        - name: domain
          in: query
          description: Domain that you want to use for the short link.
          schema:
            type: string
        - name: slug
          in: query
          description: >-
            Custom alias for the short link, must be unique, only accept letter,
            number, underscore `_` and hyphen `-`.
          schema:
            type: string
      responses:
        '200':
          description: Shortened url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortenedUrl'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ShortenedUrl:
      required:
        - code
        - urlPrefix
        - url
      type: object
      properties:
        code:
          description: The short url code
          type: string
          example: ax
        url:
          description: The normalized original url
          type: string
          example: https://google.com
        status:
          description: >-
            Status of the shortened url, it could be 'public', 'under_review'
            and 'blocked'
          type: string
          example: public
        shortened:
          description: The shortened url
          type: string
          example: https://u301.co/ax
    Error:
      required:
        - error
        - message
      type: object
      properties:
        code:
          type: string
          example: E_VALIDATION_ERROR
        message:
          type: string
          example: The url field must be a valid URL

````