Update bot

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

Overview

Partially update settings for an existing bot. The bot must already exist under your account. Only the provided fields are updated; existing values are preserved for omitted fields. The api_bot_settings object is merged into existing settings rather than replaced.

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
`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
`edit_bot_status`	"success"	Optional	Status of the update operation 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'
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

Update specific fields of a bot without affecting other settings.

curl https://api.poe.com/bots/{handle} \
-X PATCH \
-H "Authorization: Bearer sk_test_51SAMPLEKEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "api_bot_settings": {
    "pricing": {
      "prompt": "0.000002",
      "completion": "0.000008"
    }
  }
}'

Bot updated

{
"edit_bot_status": "success"
}