External Application Guide

Overview

External applications exist outside the Poe client UI. They connect to Poe via a Poe user's API key, and use the Poe API to query Poe bots and models on behalf of that user, spending the user's points in the process.

Examples of possible external applications:

  • Browser toolbars
  • Shell scripts
  • Alternative chat interfaces
  • Specialized client applications like IDEs

Querying Poe bots via an API key

All Poe API keys are associated with a user account. As a creator, you can use your own API key, meaning points will be charged to your own Poe account, or you can ask users of your product to provide their Poe API key, meaning points will be charge to their Poe account. Note that if you are creating a server bot, you can charge requests directly to the user's account without requiring an API key via Accessing other bots on Poe.

❗️ Warning

This API makes the API key owner's entire point balance available to any bot that is queried, so you may want to be careful about calling bots that are not your own or are not marked as official.

Get an API Key

Navigate to poe.com/api_key and copy your user API key (or ask your users to do the same).

Image

Install Dependencies

To use the fastapi_poe library in your project, you'll need to install it first. This can be done using pip, Python's package installer. The command pip install fastapi-poe will download and install the latest version of the library and its dependencies from PyPI (Python Package Index).

Run this command in your terminal or command prompt to complete the installation.

Call "get_bot_response" or "get_bot_response_sync".

In a python shell, run the following after replacing the placeholder with an API key.

import fastapi_poe as fp

api_key = <api_key> # replace this with your API key
message = fp.ProtocolMessage(role="user", content="Hello world")

for partial in fp.get_bot_response_sync(messages=[message], bot_name="GPT-5", api_key=api_key):
    print(partial)

For asynchronous applications, use fp.get_bot_response instead of fp.get_bot_response_sync.

import asyncio
import fastapi_poe as fp

async def get_response():
    api_key = <api_key> # replace this with your API key
    message = fp.ProtocolMessage(role="user", content="Hello world")
    async for partial in fp.get_bot_response(messages=[message], bot_name="GPT-5", api_key=api_key):
        print(partial)

def main():
    asyncio.run(get_response())

if __name__ == "__main__":
    main()

Sending files in the query

Use fp.upload_file to upload the files before sending them in the request.

import fastapi_poe as fp

api_key = <api_key> # replace this with your API key
pdf_attachment = fp.upload_file_sync(open("draconomicon.pdf", "rb"), api_key=api_key)
message = fp.ProtocolMessage(role="user", content="Hello world", attachments=[pdf_attachment])

for partial in fp.get_bot_response_sync(messages=[message], bot_name="GPT-5", api_key=api_key):
    print(partial)

Limitations:

  • Requests are rate-limited to 500 requests per minute per user.
  • Compute points are deducted directly from the account associated with the API key.

Passing Custom Parameters

Use the parameters field in ProtocolMessage to send custom parameters to bots. This includes model-specific parameters like thinking_budget for Claude models, reasoning_effort for GPT models, and bot-specific parameters like aspect_ratio for image generation bots.

Important: Parameters must be passed via the parameters attribute, NOT appended to the message content. Appending parameters like "--thinking_budget 1000" to the content string will not work when calling bots via the API.

Example: Claude models with thinking budget

import fastapi_poe as fp

api_key = <api_key> # replace this with your API key
message = fp.ProtocolMessage(
    role="user",
    content="Explain quantum computing"
)

for partial in fp.get_bot_response_sync(messages=[message], bot_name="Claude-Sonnet-4.5", api_key=api_key):
    print(partial)

Example: GPT models with reasoning effort

import fastapi_poe as fp

api_key = <api_key> # replace this with your API key
message = fp.ProtocolMessage(
    role="user",
    content="Solve this math problem: ..."
)

for partial in fp.get_bot_response_sync(messages=[message], bot_name="GPT-5", api_key=api_key):
    print(partial)

Example: Image generation with aspect ratio

import fastapi_poe as fp

api_key = <api_key> # replace this with your API key
message = fp.ProtocolMessage(
    role="user",
    content="A cat in a hat"
)

for partial in fp.get_bot_response_sync(messages=[message], bot_name="Imagen-4", api_key=api_key):
    print(partial)

Note: When using the Poe client UI, parameters like aspect ratio or quality can be specified using flags (e.g., --aspect_ratio 9:16). When using the API, these parameters can be passed via the parameters dictionary if needed for your specific use case.

Leaderboard

External applications can appear on Poe’s leaderboard by setting two optional headers when making API requests.

Poe uses these headers to attribute individual API requests to an external application. They also control how your application is displayed when it appears in a leaderboard.

HTTP-Referer

  • URL linked to when your application appears in a leaderboard.

X-Title

  • Name shown when your application appears in a leaderboard.

An external application is uniquely identified by the combination of both of these headers. It is not possible to change the title or URL associated with past requests.

# pip install openai
import os, openai

client = openai.OpenAI(
    api_key=os.getenv("POE_API_KEY"), # https://poe.com/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)
// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "your_poe_api_key", // https://poe.com/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, the universe, and everything?",
        },
    ],
});

console.log(completion.choices[0].message.content);
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."
            }
        ]
    }'

Questions?

Please contact us if you would like a higher limit or want to request any other changes to support your external application.

On this page

Overview
Querying Poe bots via an API key
Get an API Key
Install Dependencies
Call "get_bot_response" or "get_bot_response_sync".
Sending files in the query
Passing Custom Parameters
Example: Claude models with thinking budget
Example: GPT models with reasoning effort
Example: Image generation with aspect ratio
Leaderboard
Questions?