Get bot

GEThttps://api.poe.com/bots/{handle}

Overview

Retrieve details for a specific bot under your account by handle.

Authentication

Send your Poe API key in the Authorization header:

Authorization: Bearer sk_test_51SAMPLEKEY

All requests must be made over HTTPS.

Parameters

Name	Location	Type	Required	Description
`handle`	path	string	Required	The bot's unique handle

Responses

Field	Type	Required	Description
`handle`	string	Required	The bot's unique handle
`description`	string	Required	The bot's description
`is_private`	boolean	Required	Whether the bot is private
`api_bot_settings`	object	Optional	Configuration for how your bot connects to your Chat Completions API or Responses API endpoint.
`api_bot_settings.model_name`	string	Optional	Model name passed to your endpoint
`api_bot_settings.base_url`	string	Optional	Base URL of your API endpoint
`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.
`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`
`api_bot_settings.max_input_tokens`	integer	Optional	Maximum number of input tokens allowed
`api_bot_settings.context_size`	integer	Optional	Total context window size in tokens
`api_bot_settings.input_modalities`	"text" \| "image" \| "video"[]	Optional	Supported input types. Video is only supported with the Chat Completions API.
`api_bot_settings.output_modalities`	"text"[]	Optional	Supported output types
`api_bot_settings.supported_features`	"tools"[]	Optional	Supported features
`api_bot_settings.param_definitions`	object[]	Optional	Custom parameter definitions
`api_bot_settings.param_definitions[].param_name`	string	Optional	Parameter name, matches parameter_name in parameter_controls
`api_bot_settings.param_definitions[].param_dest`	"extra_body"	Optional	Where to place the parameter in the API request Allowed values: `extra_body`
`api_bot_settings.param_definitions[].default_value`	unknown	Optional	Default value when the user has not set the parameter
`api_bot_settings.pricing`	object	Optional	Per-token pricing configuration. Prices are string decimal values representing dollar cost per single token.
`api_bot_settings.pricing.prompt`	string	Optional	Price per input token
`api_bot_settings.pricing.completion`	string	Optional	Price per output token
`api_bot_settings.pricing.input_cache_reads`	string	Optional	Price per cached input token
`api_bot_settings.pricing.context_pricing`	object	Optional	Multi-tier context pricing with per-token prices per tier.
`parameter_controls`	object	Optional	UI controls displayed to users when interacting with your bot.
`parameter_controls.api_version`	"2"	Optional	Must be "2" Allowed values: `2`
`parameter_controls.sections`	object[]	Optional
`parameter_controls.sections[].name`	string	Optional	Section header label
`parameter_controls.sections[].controls`	object[]	Optional
`parameter_controls.sections[].collapsed_by_default`	boolean	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.
404	`error`	Not found Bot MyBot does not exist or access denied

🔁 Callbacks & webhooks

No callbacks or webhooks are associated with this endpoint.

Code example

Retrieve details for a specific bot by handle.

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

Example response

{
"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"
  }
}
}