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

# Shorten Long URLs

> This endpoint allows you to shorten a URL. The request payload must contain the URL to be shortened, along with optional parameters for customization.



## OpenAPI

````yaml POST /
openapi: 3.0.3
info:
  title: Spoo.me API
  description: >-
    Spoo.me is a free and open-source URL shortening service that provides
    powerful features for creating and managing shortened URLs with
    comprehensive analytics.
  version: 0.0.1
  contact:
    name: Spoo.me Support
    url: https://spoo.me/contact
    email: support@spoo.me
  license:
    name: Apache 2.0
    url: https://github.com/spoo-me/spoo/blob/main/LICENSE
servers:
  - url: https://spoo.me
    description: Production server
security: []
tags:
  - name: URL Shortening
    description: Operations for creating shortened URLs
  - name: Analytics
    description: Operations for retrieving URL analytics and statistics
  - name: Data Export
    description: Operations for exporting URL data in various formats
paths:
  /:
    post:
      tags:
        - URL Shortening
      summary: Shorten Long URLs
      description: >-
        This endpoint allows you to shorten a URL. The request payload must
        contain the URL to be shortened, along with optional parameters for
        customization.
      operationId: shortenUrl
      parameters:
        - name: Accept
          in: header
          required: true
          description: Must be set to application/json to receive JSON responses
          schema:
            type: string
            enum:
              - application/json
            default: application/json
          example: application/json
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    The long URL to be shortened. Must include a valid protocol
                    (http/https) and follow RFC-1034 & RFC-2727 standards.
                  example: https://example.com
                alias:
                  type: string
                  maxLength: 16
                  pattern: ^[a-zA-Z0-9]+$
                  description: >-
                    Custom alias for the shortened URL. Must be alphanumeric and
                    maximum 16 characters. Anything beyond 16 characters will be
                    **stripped by the API**.
                  example: example
                password:
                  type: string
                  minLength: 8
                  description: >-
                    Password to access the shortened URL. Must be at least 8
                    characters long, contain at least one letter, one number,
                    and one special character ('@' or '.').
                  example: SuperStrongPassword@18322
                max-clicks:
                  type: integer
                  minimum: 1
                  description: >-
                    Maximum number of clicks allowed for the shortened URL. Must
                    be a positive integer.
                  example: 10
                block-bots:
                  type: boolean
                  description: Whether to block bots from accessing the shortened URL.
                  example: false
      responses:
        '200':
          description: URL successfully shortened
          content:
            application/json:
              schema:
                type: object
                properties:
                  short_url:
                    type: string
                    format: uri
                    description: The shortened URL
                    example: https://spoo.me/example
                  domain:
                    type: string
                    format: host
                    description: The domain of the shortened URL
                    example: spoo.me
                  original_url:
                    type: string
                    format: uri
                    description: The original URL
                    example: https://example.com
        '400':
          description: Bad Request - Various validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UrlError:
                  summary: Invalid or missing URL
                  value:
                    error: UrlError
                    message: Invalid or missing URL
                AliasError:
                  summary: Invalid or taken alias
                  value:
                    error: AliasError
                    message: Alias is invalid or already taken
                PasswordError:
                  summary: Password requirements not met
                  value:
                    error: PasswordError
                    message: Password does not meet requirements
                MaxClicksError:
                  summary: Invalid max-clicks value
                  value:
                    error: MaxClicksError
                    message: Max clicks must be a positive integer
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: RateLimitError
                message: Rate limit exceeded. Please try again later.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type identifier
        message:
          type: string
          description: Human-readable error message
      required:
        - error
        - message

````