X2Y API Documentation

Integrate URL shortening, QR code generation, and link management into your own applications via our REST API.

Authentication

All API requests require a valid API key. You can generate keys from your Profile → API Keys page.

Note: API keys require an Active account. New accounts start as Pending and must be approved by an admin.

Pass your key in one of two ways:

# Option 1: Query parameter
GET https://x2y.me/api.php?api_key=YOUR_KEY&url=https://example.com

# Option 2: Authorization header (preferred)
GET https://x2y.me/api.php?url=https://example.com
Authorization: Bearer YOUR_KEY
                

Shorten a URL

Creates or updates a shortened URL and returns the result.

GET POST https://x2y.me/api.php

Parameters

Parameter	Required	Description
`api_key`	Required	Your API key
`url`	Required	The long URL to shorten (must include http:// or https://)
`name`	Optional	Custom short name (alphanumeric, hyphens, underscores; min 4 chars). Auto-generated if omitted.
`date`	Optional	Expiration date in YYYY-MM-DD format. Defaults to 1 year.
`return`	Optional	`json` (default), `url`, `name`, `qr`, `barcode`

Example: JSON Response (default)

curl "https://x2y.me/api.php?api_key=x2y_abc123...&url=https://example.com/long/path"
                

{
  "success": true,
  "short_url":  "https://x2y.me/Ab3Kz",
  "short_name": "Ab3Kz",
  "long_url":   "https://example.com/long/path",
  "qr_url":     "https://api.qrserver.com/v1/create-qr-code/?...",
  "expires":    "2027-07-18 23:59:59"
}
                

Example: Custom name + QR image URL

curl "https://x2y.me/api.php?api_key=x2y_abc123...&url=https://example.com&name=my-link&return=qr"

# Returns (plain text):
https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https%3A%2F%2Fx2y.me%2Fmy-link
                

JavaScript Fetch Example

const response = await fetch('https://x2y.me/api.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Bearer x2y_abc123...'
  },
  body: new URLSearchParams({
    url:  'https://example.com/very/long/url',
    name: 'my-custom-name',  // optional
    date: '2027-01-18'  // optional
  })
});
const data = await response.json();
console.log(data.short_url); // "https://x2y.me/my-custom-name"
                

Parameter Passing

X2Y automatically forwards any query parameters appended to the short URL to the destination. For example:

# Short URL
https://x2y.me/my-link?user_id=42&source=email

# Redirects to (destination URL + passed params)
https://example.com/page?user_id=42&source=email
                

Error Codes

HTTP Code	Error Message	Cause
`400`	Missing parameter: url	No URL provided
`400`	Invalid URL format	URL doesn't start with http(s)
`401`	Missing api_key	No key provided
`401`	Invalid or revoked API key	Key doesn't exist or was revoked
`403`	Account not active	Account still Pending admin approval
`400`	Name already taken	Custom name belongs to another user

Quick Reference

Base URL: https://x2y.me/api.php
Methods: GET, POST
Auth: api_key param or Bearer token
Response: JSON (default)
QR via api.qrserver.com
Max expiry: 3 years
Max API keys: 5 per account

Get Started

Create Free Account Login