> ## 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. # Create Shortened URL > Create a new shortened URL. Create a shortened URL with optional customization including password protection, expiration, click limits, and bot blocking. **Authentication**: Optional — higher rate limits when authenticated. **API Key Scope**: `shorten:create` or `admin:all` **Rate Limits**: - Authenticated: 60/min, 5,000/day - Anonymous: 20/min, 1,000/day **Anonymous Usage Consequences**: - Lower rate limits - Cannot manage or view URLs later - Cannot use private stats - URLs not linked to any account ## OpenAPI ````yaml /openapi-v1.json post /api/v1/shorten openapi: 3.1.0 info: title: spoo.me description: >- REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day. Authenticate using either: - **API Key**: `Authorization: Bearer spoo_` - **JWT Token**: `Authorization: Bearer ` (obtained via /auth/login) - **Session Cookie**: `access_token` cookie (set automatically on login) contact: name: spoo.me url: https://spoo.me/contact email: support@spoo.me license: name: Apache 2.0 url: https://github.com/spoo-me/spoo/blob/main/LICENSE version: 1.0.0 servers: - url: https://spoo.me description: Production security: - ApiKeyAuth: [] - JWTAuth: [] tags: - name: URL Shortening description: Create new shortened URLs - name: Link Management description: List, update, and delete your shortened URLs - name: Statistics description: Click analytics and data export - name: API Keys description: Create and manage API keys for programmatic access - name: Authentication description: Login, register, password management, and email verification - name: OAuth description: OAuth provider login, linking, and unlinking - name: System description: Health checks and server metrics paths: /api/v1/shorten: post: tags: - URL Shortening summary: Create Shortened URL description: >- Create a new shortened URL. Create a shortened URL with optional customization including password protection, expiration, click limits, and bot blocking. **Authentication**: Optional — higher rate limits when authenticated. **API Key Scope**: `shorten:create` or `admin:all` **Rate Limits**: - Authenticated: 60/min, 5,000/day - Anonymous: 20/min, 1,000/day **Anonymous Usage Consequences**: - Lower rate limits - Cannot manage or view URLs later - Cannot use private stats - URLs not linked to any account operationId: shortenUrl requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateUrlRequest' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UrlResponse' '400': description: Bad Request — invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden — insufficient permissions or scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict — resource already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - {} - ApiKeyAuth: [] - JWTAuth: [] components: schemas: CreateUrlRequest: properties: long_url: type: string title: Long Url description: >- The destination URL to shorten. Must be a valid http:// or https:// URL. examples: - https://example.com/very/long/url/path alias: anyOf: - type: string - type: 'null' title: Alias description: >- Custom short code. Alphanumeric, hyphens, underscores. 3-16 chars. Auto-generated if omitted. examples: - mylink password: anyOf: - type: string - type: 'null' title: Password description: >- Password to protect the URL. Min 8 chars, must contain letter + number + special char. examples: - secure@123 block_bots: anyOf: - type: boolean - type: 'null' title: Block Bots description: Block known bot user agents from accessing the URL. max_clicks: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Max Clicks description: Maximum clicks before the URL expires. Must be positive. examples: - 100 expire_after: anyOf: - type: string - type: integer - type: 'null' title: Expire After description: >- Expiration time. ISO 8601 string (e.g. `2025-12-31T23:59:59Z`) or Unix epoch seconds (e.g. `1735689599`). examples: - '2025-12-31T23:59:59Z' - 1735689599 private_stats: anyOf: - type: boolean - type: 'null' title: Private Stats description: >- Make statistics private (only owner can view). Requires authentication. type: object required: - long_url title: CreateUrlRequest description: >- Request body for creating a new shortened URL. Accepts ``url`` as an alias for ``long_url`` — the existing API supports both. UrlResponse: properties: alias: type: string title: Alias description: Short code for the URL. examples: - mylink short_url: type: string title: Short Url description: Full shortened URL ready for sharing. examples: - https://spoo.me/mylink long_url: type: string title: Long Url description: Original destination URL. examples: - https://example.com/long/url owner_id: anyOf: - type: string - type: 'null' title: Owner Id description: User ID if authenticated, null for anonymous URLs. examples: - 507f1f77bcf86cd799439011 created_at: type: integer title: Created At description: Creation time as Unix timestamp. examples: - 1704067200 status: type: string title: Status description: URL status. examples: - ACTIVE private_stats: anyOf: - type: boolean - type: 'null' title: Private Stats description: Whether statistics are private (owner-only). type: object required: - alias - short_url - long_url - created_at - status title: UrlResponse description: >- Response body for a newly created shortened URL (POST /api/v1/shorten). ``created_at`` is a Unix timestamp integer — matching the existing endpoint. ErrorResponse: properties: error: type: string title: Error error_code: type: string title: Error Code field: anyOf: - type: string - type: 'null' title: Field details: anyOf: - {} - type: 'null' title: Details type: object required: - error - error_code title: ErrorResponse description: Standard error JSON body produced by the AppError exception handler. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: spoo_ description: 'API key authentication. Pass your key as: `Bearer spoo_`' JWTAuth: type: http scheme: bearer bearerFormat: JWT description: 'JWT access token from /auth/login. Pass as: `Bearer `' ````