Poe API Documentation

Appearance

Workflow 003: Leaderboard Integration ​

Fresh 🌱

Workflow ID: WF-003
Version: 1.0
Status: Active

Overview ​

Integrate your external application with Poe's leaderboard system by setting custom headers. This allows your application to appear on Poe's leaderboard with a custom name and URL.

Prerequisites ​

  • [x] API key obtained (SOP 001)
  • [x] External application set up (Workflow 001)
  • Understanding of HTTP headers

Workflow Steps ​

┌─────────────────────────────────────────────────────────────┐
│              LEADERBOARD INTEGRATION                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Define App Info ──► 2. Set Headers                        │
│        │                        │                            │
│        └──► 3. Make Requests ───┘                            │
│        │                        │                            │
│        └──► 4. Verify on Leaderboard ─┘                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Required Headers ​

Two headers control leaderboard appearance:

  • HTTP-Referer: URL linked when your app appears in leaderboard
  • X-Title: Name shown in leaderboard

Important

Your application is uniquely identified by the combination of BOTH headers. You cannot change the title or URL for past requests.

Procedure ​

Step 1: Define Your Application Info ​

python
APP_TITLE = "My Poe App"
APP_URL = "https://my-poe-app.com"

Step 2: Using OpenAI-Compatible API (Python) ​

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("POE_API_KEY"),
    base_url="https://api.poe.com/v1",
)

chat = client.chat.completions.create(
    extra_headers={
        "HTTP-Referer": "https://my-poe-app.com",
        "X-Title": "My Poe App",
    },
    model="Claude-Opus-4.1",
    messages=[{"role": "user", "content": "Top 3 things to do in NYC?"}],
)

print(chat.choices[0].message.content)

Step 3: Using OpenAI-Compatible API (Node.js) ​

javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "your_poe_api_key",
    baseURL: "https://api.poe.com/v1",
    defaultHeaders: {
        "HTTP-Referer": "https://my-poe-app.com",
        "X-Title": "My Poe App",
    },
});

const completion = await client.chat.completions.create({
    model: "Grok-4",
    messages: [
        {
            role: "user",
            content: "What is the meaning of life?",
        },
    ],
});

console.log(completion.choices[0].message.content);

Step 4: Using cURL ​

bash
curl "https://api.poe.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $POE_API_KEY" \
    -H "HTTP-Referer: https://my-poe-app.com" \
    -H "X-Title: My Poe App" \
    -d '{
        "model": "Claude-Sonnet-4.5",
        "messages": [
            {
                "role": "user",
                "content": "Write a one-sentence bedtime story about a unicorn."
            }
        ]
    }'

Complete Example: Python Client with Leaderboard ​

python
import os
from openai import OpenAI
from typing import Optional

class PoeLeaderboardClient:
    def __init__(
        self,
        api_key: Optional[str] = None,
        app_title: str = "My Poe App",
        app_url: str = "https://my-poe-app.com"
    ):
        self.api_key = api_key or os.getenv("POE_API_KEY")
        self.app_title = app_title
        self.app_url = app_url
        
        self.client = OpenAI(
            api_key=self.api_key,
            base_url="https://api.poe.com/v1",
        )
    
    def query(
        self,
        model: str,
        messages: list,
        **kwargs
    ):
        """Query Poe API with leaderboard headers."""
        return self.client.chat.completions.create(
            extra_headers={
                "HTTP-Referer": self.app_url,
                "X-Title": self.app_title,
            },
            model=model,
            messages=messages,
            **kwargs
        )
    
    def simple_query(self, model: str, prompt: str):
        """Simple query helper."""
        return self.query(
            model=model,
            messages=[{"role": "user", "content": prompt}]
        )

# Usage
if __name__ == "__main__":
    client = PoeLeaderboardClient(
        app_title="My Awesome App",
        app_url="https://myawesomeapp.com"
    )
    
    response = client.simple_query(
        model="Claude-Opus-4.1",
        prompt="What are the top 3 programming languages in 2025?"
    )
    
    print(response.choices[0].message.content)

Complete Example: Using fastapi-poe with Custom Headers ​

If you need to use fastapi-poe library with leaderboard headers, you'll need to modify the HTTP requests. However, the OpenAI-compatible API is recommended for leaderboard integration.

Verification ​

After making requests with the headers:

  1. Check your requests are being made with correct headers
  2. Wait for leaderboard update (may take some time)
  3. Check Poe leaderboard to see if your app appears
  4. Verify title and URL match what you set

Best Practices ​

  1. Use consistent headers - Don't change them frequently
  2. Use meaningful titles - Make your app easily identifiable
  3. Use valid URLs - Ensure your referer URL is accessible
  4. Test headers - Verify they're being sent correctly
  5. Monitor leaderboard - Check your app's position

Header Guidelines ​

HTTP-Referer ​

  • Should be a valid, accessible URL
  • Can be your app's homepage or documentation
  • Will be linked when your app appears in leaderboard
  • Should be consistent across all requests

X-Title ​

  • Should be a short, descriptive name
  • Will be displayed in leaderboard
  • Should be consistent across all requests
  • Max recommended length: 50 characters

Troubleshooting ​

Problem: App not appearing on leaderboard
Solution:

  • Verify headers are being sent correctly
  • Check header names are exact: HTTP-Referer and X-Title
  • Ensure you're making actual API requests (not just testing)
  • Wait for leaderboard to update (can take time)

Problem: Wrong title/URL on leaderboard
Solution:

  • Headers are set per-request
  • Past requests cannot be changed
  • Use consistent headers going forward

Problem: Headers not working with fastapi-poe
Solution:

  • Use OpenAI-compatible API for leaderboard integration
  • Or modify fastapi-poe's HTTP client to include headers

Example: Multiple Apps ​

If you have multiple applications:

python
# App 1
client1 = PoeLeaderboardClient(
    app_title="My Python Tool",
    app_url="https://mypythontool.com"
)

# App 2
client2 = PoeLeaderboardClient(
    app_title="My Node.js App",
    app_url="https://mynodejsapp.com"
)

# Each will appear separately on leaderboard

See Also ​

Next: Quick Reference Overview

Poe API Documentation

Copyright © 2025