~~ DEVELOPER QUICK START ~~

🐦 Send your first carrier pigeon in 60 seconds flat. 🐦

Copy. Paste. Launch. That's it.

🆓 FREE TIER - NO AUTH REQUIRED

Try our API with zero friction. No signup, no API keys, just pure pigeon facts!

🆓 Free Pigeon Fact Endpoint

# No auth required - just call it!
curl https://pigeonapi-4ma3.polsia.app/api/pigeon-fact

# Response:
{
  "fact": "Pigeons can recognize all 26 letters of the English alphabet...",
  "pigeon_name": "Sir Coos-a-Lot",
  "powered_by": "PigeonMail — pigeonapi-4ma3.polsia.app"
}

🌟 FREE TIER LIMITS

100 requests per hour per IP
Perfect for testing, personal projects, or just learning fun pigeon facts!

CORS enabled - call from any frontend!

Want to send actual carrier pigeon messages? Sign up below 👇

1 Get Your Roost Access

First, you need a PigeonMail account. No API keys - we use session authentication!

QUICK SIGNUP

Don't have an account? Sign up here to join the flock (takes 30 seconds)

2 Send Your First Pigeon

Pick your poison. All examples are ready to run - just replace the email addresses!

📡 cURL (Command Line)

# First, login to get your session cookie
curl -X POST https://pigeonapi-4ma3.polsia.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }' \
  -c cookies.txt

# Now send a pigeon using the session
curl -X POST https://pigeonapi-4ma3.polsia.app/api/pigeons/send \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "recipient_email": "friend@example.com",
    "recipient_name": "Best Friend",
    "content": "Hello from my first carrier pigeon! 🐦",
    "bird_type": "standard_pigeon"
  }'

🟢 Node.js / JavaScript

const BASE_URL = 'https://pigeonapi-4ma3.polsia.app';

// 1. Login to get session cookie
const loginResponse = await fetch(`${BASE_URL}/api/auth/login`, {
  method: 'POST',
  credentials: 'include',  // Important!
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'your-email@example.com',
    password: 'your-password'
  })
});

const loginData = await loginResponse.json();
console.log('Logged in:', loginData.user.email);

// 2. Send a pigeon
const pigeonResponse = await fetch(`${BASE_URL}/api/pigeons/send`, {
  method: 'POST',
  credentials: 'include',  // Don't forget this!
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipient_email: 'friend@example.com',
    recipient_name: 'Best Friend',
    content: 'Hello from my first carrier pigeon! 🐦',
    bird_type: 'standard_pigeon'
  })
});

const pigeon = await pigeonResponse.json();
console.log('Pigeon dispatched!', pigeon.pigeon.tracking_code);
console.log('Track at:', pigeon.pigeon.track_url);

🐍 Python (requests)

import requests

BASE_URL = 'https://pigeonapi-4ma3.polsia.app'

# Create a session to persist cookies
session = requests.Session()

# 1. Login to get session cookie
login_response = session.post(
    f'{BASE_URL}/api/auth/login',
    json={
        'email': 'your-email@example.com',
        'password': 'your-password'
    }
)
login_data = login_response.json()
print(f"Logged in: {login_data['user']['email']}")

# 2. Send a pigeon (session automatically includes cookies)
pigeon_response = session.post(
    f'{BASE_URL}/api/pigeons/send',
    json={
        'recipient_email': 'friend@example.com',
        'recipient_name': 'Best Friend',
        'content': 'Hello from my first carrier pigeon! 🐦',
        'bird_type': 'standard_pigeon'
    }
)

pigeon = pigeon_response.json()
print(f"Pigeon dispatched! Tracking: {pigeon['pigeon']['tracking_code']}")
print(f"Track at: {pigeon['pigeon']['track_url']}")

⚠️ COOKIE REMINDER

Session-based auth means:
• Always include credentials: 'include' in fetch()
• Use requests.Session() in Python
• Save cookies with -c cookies.txt and load with -b cookies.txt in cURL

3 Understand the Response

When you dispatch a pigeon, you'll get back all the flight details:

📬 Success Response (200 OK)

{
  "success": true,
  "pigeon": {
    "tracking_code": "A1B2C3D4E5F6",      // Use this to track!
    "delivery_eta": "2026-02-12T15:30:00Z",  // When it arrives
    "wing_hours": 48,                    // Flight duration
    "is_express": false,
    "bird_type": "standard_pigeon",
    "bird_name": "Standard Pigeon",
    "bird_emoji": "🐦",
    "track_url": "/track/A1B2C3D4E5F6"   // Public tracking page
  },
  "message": "Your Standard Pigeon has taken flight! 🐦"
}

🗺️ TRACK YOUR PIGEON

Use the tracking_code to check flight status:

GET https://pigeonapi-4ma3.polsia.app/api/pigeons/track/{tracking_code}

Or visit the public tracking page at /track/{tracking_code}

NEXT STEPS

🐦 You're ready to fly! Here's what to explore next:

📚

Full API Docs

Explore all endpoints, bird types, and rate limits

View Docs

🎮

Try the Demo

Send a pigeon without writing code

Try Demo

💎

Go Premium

Unlock Racing Homers, Owls, and Pelicans

See Pricing

🐦 AVAILABLE BIRDS

Bird Type	ID	Delivery Time	Tier
🐦 Standard Pigeon	standard_pigeon	24-72 hours	Free
🏎️ Racing Homer	racing_homer	1-6 hours	Premium
🦉 Homing Owl	homing_owl	12-24 hours	Premium
🦅 Pelican Post	pelican_post	24-48 hours	Premium

~*~ DEVELOPER QUICK START ~*~

🆓 FREE TIER - NO AUTH REQUIRED

NEXT STEPS

🐦 AVAILABLE BIRDS

~~ DEVELOPER QUICK START ~~