List bots

GEThttps://api.poe.com/bots

Overview

Returns all API Bots under your account.

Authentication

Send your Poe API key in the Authorization header:

Authorization: Bearer sk_test_51SAMPLEKEY

All requests must be made over HTTPS.

Parameters

This endpoint does not accept query or path parameters.

Responses

Field	Type	Required	Description
`bots`	object[]	Required
`bots[].handle`	string	Required	The bot's unique handle
`bots[].description`	string	Required	The bot's description
`bots[].is_private`	boolean	Required	Whether the bot is private
`bots[].api_bot_settings`	object	Optional	Configuration for how your bot connects to your Chat Completions API or Responses API endpoint.
`bots[].api_bot_settings.model_name`	string	Optional	Model name passed to your endpoint
`bots[].api_bot_settings.base_url`	string	Optional	Base URL of your API endpoint
`bots[].api_bot_settings.api_key`	string	Optional	API key for authenticating requests to your endpoint. Encrypted at rest. Only accepted on write requests; not returned in responses.
`bots[].api_bot_settings.api_type`	"chat_completions_api" \| "responses_api"	Optional	API format: chat_completions_api or responses_api Allowed values: `chat_completions_api`, `responses_api`
`bots[].api_bot_settings.max_input_tokens`	integer	Optional	Maximum number of input tokens allowed
`bots[].api_bot_settings.context_size`	integer	Optional	Total context window size in tokens
`bots[].api_bot_settings.input_modalities`	"text" \| "image" \| "video"[]	Optional	Supported input types. Video is only supported with the Chat Completions API.
`bots[].api_bot_settings.output_modalities`	"text"[]	Optional	Supported output types
`bots[].api_bot_settings.supported_features`	"tools"[]	Optional	Supported features
`bots[].api_bot_settings.param_definitions`	object[]	Optional	Custom parameter definitions
`bots[].api_bot_settings.pricing`	object	Optional	Per-token pricing configuration. Prices are string decimal values representing dollar cost per single token.
`bots[].parameter_controls`	object	Optional	UI controls displayed to users when interacting with your bot.
`bots[].parameter_controls.api_version`	"2"	Optional	Must be "2" Allowed values: `2`
`bots[].parameter_controls.sections`	object[]	Optional

❌ Error codes

Http	Type	Description
401	`error`	Authentication failed Incorrect API key provided. You can find your API key at https://poe.com/api/keys.

🔁 Callbacks & webhooks

No callbacks or webhooks are associated with this endpoint.

Code example

Retrieve all API Bots under your account.

curl https://api.poe.com/bots \
-H "Authorization: Bearer sk_test_51SAMPLEKEY" \
-H "Accept: application/json"

Example response

{
"bots": [
  {
    "handle": "MyCustomBot",
    "description": "A custom bot powered by a chat completions endpoint",
    "is_private": true,
    "api_bot_settings": {
      "model_name": "my-model",
      "base_url": "https://api.example.com/v1",
      "api_type": "chat_completions_api",
      "input_modalities": [
        "text",
        "image"
      ],
      "output_modalities": [
        "text"
      ],
      "supported_features": [
        "tools"
      ],
      "max_input_tokens": 128000,
      "pricing": {
        "prompt": "0.00003",
        "completion": "0.00006"
      }
    }
  }
]
}