Replace bot

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

Overview

Create a bot or replace all settings for an existing bot. If a bot with the given handle already exists under your account, its settings are replaced entirely. Otherwise, a new bot is created. Unlike POST, the handle is specified in the URL path and api_bot_settings is replaced entirely rather than merged.

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

Request body

Field	Type	Required	Description
`description`	string	Optional	Bot description
`is_private`	boolean	Optional	Whether the bot is private Default: `true`
`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

Responses

Field	Type	Required	Description
`create_bot_status`	"success"	Optional	Present when a new bot was created Allowed values: `success`
`edit_bot_status`	"success"	Optional	Present when an existing bot was replaced Allowed values: `success`

❌ Error codes

Http	Type	Description
400	`error`	Bad request Invalid request body
401	`error`	Authentication failed Incorrect API key provided. You can find your API key at https://poe.com/api/keys.
403	`error`	Forbidden Unauthorized to edit bot 'BotHandle'

🔁 Callbacks & webhooks

No callbacks or webhooks are associated with this endpoint.

Code example

Replace all settings for a bot. The api_bot_settings object is replaced entirely.

curl https://api.poe.com/bots/{handle} \
-X PUT \
-H "Authorization: Bearer sk_test_51SAMPLEKEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "description": "Fully replaced bot configuration",
  "api_bot_settings": {
    "model_name": "my-org/my-new-model",
    "base_url": "https://api.example.com/v1",
    "api_key": "YOUR_API_KEY",
    "input_modalities": [
      "text"
    ],
    "output_modalities": [
      "text"
    ],
    "pricing": {
      "prompt": "0.000001",
      "completion": "0.000004"
    }
  }
}'

Bot replaced

{
"edit_bot_status": "success"
}