~*~ THE NEST API ~*~

Welcome, fellow pigeon handler! The NEST (Networking Efficient Slow Transmission) API lets you integrate artisanal slow messaging into your applications. Why rush when you can coo?

PIGEON PRO TIP
All Nesting Spots (endpoints) return JSON. Pigeons are multilingual but prefer JSON.

Base Roost URL

https://pigeonapi-4ma3.polsia.app

ROOST AUTHENTICATION

The NEST API uses session-based authentication. After joining the flock or returning to the roost, your session cookie grants you access to the coop.

IMPORTANT
Make sure to include credentials in your fetch requests: credentials: 'include'
fetch('/api/pigeons/send', { method: 'POST', credentials: 'include', // Don't forget this! headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ... }) });

🐦 FLOCK CAPACITY 🐦

Our coop has limited space! Here's how many pigeons you can dispatch:

DEMO API - DAILY LIMITS
Free Tier 10 requests/day
Premium Tier ($1/mo) 100 requests/day

⏰ Resets daily at midnight UTC

AUTHENTICATED API - MONTHLY LIMITS
Free Roost 3 pigeons/month
Premium Flock 20 pigeons/month
RATE LIMIT HEADERS
Every API response includes these headers:
X-RateLimit-Limit: 10 X-RateLimit-Remaining: 7 X-RateLimit-Reset: 1738108800 // Unix timestamp
COOP FULL?
When you exceed your flock capacity, you'll receive a 429 Too Many Requests response. Upgrade to Premium for more birds!
POST /api/auth/signup Join the Flock

Register a new pigeon handler account. Welcome to the coop! 🐦

Request Payload

Field Type Description
email required string Your nest address (email)
password required string Your secret coop code
name optional string What the pigeons should call you
Example Dispatch & Arrival ▶
POST /api/auth/signup Content-Type: application/json { "email": "birblover@example.com", "password": "c00c00secure123", "name": "Pigeon Pete" }
{ "success": true, "user": { "id": 42, "email": "birblover@example.com", "name": "Pigeon Pete", "tier": "free" } }

Response Codes

200 Welcome to the flock! 400 Email already nesting
POST /api/auth/login Return to Roost

Authenticate an existing pigeon handler. The roost remembers you!

Request Payload

Field Type Description
email required string Your registered nest address
password required string Your secret coop code
Example Dispatch & Arrival ▶
POST /api/auth/login Content-Type: application/json { "email": "birblover@example.com", "password": "c00c00secure123" }
{ "success": true, "user": { "id": 42, "email": "birblover@example.com", "name": "Pigeon Pete", "tier": "premium" } }

Response Codes

200 Welcome back! 401 Invalid credentials
POST /api/auth/logout Fly Away

End your session and leave the roost. Safe travels! 🕊️

NO PAYLOAD NEEDED
Just send an empty POST request. The roost knows who you are.
Example Dispatch & Arrival ▶
POST /api/auth/logout
{ "success": true }

Response Codes

200 Goodbye, friend!
GET /api/auth/me Who Am I?

Get your current pigeon handler profile. Existential crisis solved!

Example Arrival ▶
{ "user": { "id": 42, "email": "birblover@example.com", "name": "Pigeon Pete", "tier": "premium", "pigeons_sent": 7, "pigeons_limit": 20, "is_premium": true } }

Response Codes

200 Here's your info! 401 Not in the roost
GET /api/pigeons/bird-types Available Birds

Discover all the magnificent birds in our aviary. Each has unique delivery characteristics!

BIRD ROSTER
  • Standard Pigeon - The reliable classic (24-72 hrs)
  • Racing Homer - Speed demon! (1-6 hrs) PREMIUM
  • Homing Owl - Mysterious night messenger (12-24 hrs) PREMIUM
  • Pelican Post - The cargo bird, carries attachments! (24-48 hrs) PREMIUM
Example Arrival ▶
{ "bird_types": [ { "id": "standard_pigeon", "name": "Standard Pigeon", "emoji": "🐦", "description": "A reliable messenger bird...", "premium": false, "available": true, "deliveryRange": "24-72 hours", "color": "#808080" }, // ... more birds ... ], "is_premium": false }

Response Codes

200 Birds available! 401 Must be in roost
POST /api/pigeons/send Dispatch a Pigeon

Release a carrier pigeon with your message! This is the main event, folks. 🐦✉️

Request Payload

Field Type Description
recipient_email required string Where should the pigeon fly to?
content required string Your message (max 5,000 characters - pigeons have limits!)
recipient_name optional string The recipient's name for a personal touch
bird_type optional string Choose your bird: standard_pigeon, racing_homer, homing_owl, pelican_post
Example Dispatch & Arrival ▶
POST /api/pigeons/send Content-Type: application/json { "recipient_email": "friend@example.com", "recipient_name": "Best Friend", "content": "Hello from the past! This message is traveling slowly, like a fine wine.", "bird_type": "racing_homer" }
{ "success": true, "pigeon": { "tracking_code": "A1B2C3D4E5F6", "delivery_eta": "2026-01-20T13:45:00.000Z", "wing_hours": 3, "is_express": true, "bird_type": "racing_homer", "bird_name": "Racing Homer", "bird_emoji": "🏎️", "track_url": "/track/A1B2C3D4E5F6" }, "message": "Your Racing Homer has taken flight! 🏎️ Estimated delivery: 3 wing-hours" }

Response Codes

200 Pigeon dispatched! 400 Pigeon confused (bad request) 403 Premium bird required 429 Pigeon coop empty
GET /api/pigeons/track/:code Locate Your Pigeon

Track your pigeon's journey in real-time! See where they're resting, what adventures they've had. This endpoint is PUBLIC - no authentication needed! 🗺️

Path Parameters

Parameter Type Description
code required string The 12-character tracking code (case-insensitive)
Example Arrival ▶
{ "tracking_code": "A1B2C3D4E5F6", "status": "in_flight", "progress": 45, "current_status": "Stopped for a snack near the Alps", "emoji": "🏔️", "location": { "location": "the Alps", "emoji": "🏔️", "event": "Stopped for a snack", "progress": 45 }, "flight_path": [ /* array of stops */ ], "created_at": "2026-01-20T10:00:00.000Z", "delivery_eta": "2026-01-20T13:45:00.000Z", "sender_name": "Pigeon Pete", "bird_type": { "id": "racing_homer", "name": "Racing Homer", "emoji": "🏎️", "color": "#FF4500" } }

Status Values

Status Description
in_flight Pigeon is en route, having adventures
arriving Almost there! (95%+ progress)
delivered Message has landed! 📬

Response Codes

200 Pigeon located! 404 Pigeon not found
GET /api/pigeons/dashboard Your Roost

View all your dispatched pigeons and their current status. Your personal aviary overview! 🏠

Example Arrival ▶
{ "pigeons": [ { "id": 123, "recipient_email": "friend@example.com", "recipient_name": "Best Friend", "tracking_code": "A1B2C3D4E5F6", "status": "in_flight", "bird_type": "racing_homer", "preview": "Hello from the past! This message...", "created_at": "2026-01-20T10:00:00.000Z", "delivery_at": "2026-01-20T13:45:00.000Z", "current_status": { /* status object */ } } ], "stats": { "total": 15, "in_flight": 3, "delivered": 12 } }

Response Codes

200 Here's your flock! 401 Not in the roost

READY TO FLY?

Join thousands of pigeon handlers sending artisanal slow messages!

>> JOIN THE FLOCK <<