Published API Endpoints

Overview

Published API endpoints allow you to publish bots as standalone APIs with their own endpoints, API keys, rate limits, and CORS configuration. This is ideal for integrating bots into external applications.

Bot Publication Flow

Publish a Bot: Create an API Gateway deployment for a shared bot
Create API Keys: Generate API keys for authentication
Use Published API: Call the bot through its dedicated endpoint
Manage & Monitor: Update settings or delete the publication

Publish Bot

Path Parameters

bot_id

string

required

The bot ID to publish (must be a shared bot you own)

Request Body

stage

string

API Gateway stage name (e.g., "dev", "stg", "prd"). Defaults to "api" if not specified.

quota

object

Request quota configuration

Show quota properties

limit

integer

Maximum number of requests allowed in the period (must be positive). If null, no quota is applied.

offset

integer

Offset for quota calculation

period

string

Time period for quota: "DAY", "WEEK", or "MONTH". Required if limit is set.

throttle

object

Request throttling configuration

Show throttle properties

rate_limit

float

Maximum requests per second (must be positive). If null, no throttling is applied.

burst_limit

integer

Maximum burst of concurrent requests (must be positive). Required if rate_limit is set.

allowed_origins

array

required

Array of allowed CORS origins. Each must start with "http://" or "https://", or be "*" for all origins.

Requirements

Bot must be shared (not private)
Bot must not already be published
No CloudFormation deployment can be in progress

Example Request

{
  "stage": "prod",
  "quota": {
    "limit": 10000,
    "offset": 0,
    "period": "MONTH"
  },
  "throttle": {
    "rate_limit": 10.0,
    "burst_limit": 20
  },
  "allowed_origins": [
    "https://app.example.com",
    "https://dashboard.example.com"
  ]
}

Get Bot Publication

Path Parameters

bot_id

string

required

The published bot ID

Response

stage

string

The API Gateway stage (e.g., "dev", "stg", "prd")

quota

object

Quota configuration

throttle

object

Throttling configuration

allowed_origins

array

Array of allowed CORS origins

cfn_status

string

CloudFormation deployment status

codebuild_id

string

CodeBuild project ID for the deployment

codebuild_status

string

CodeBuild status: "IN_PROGRESS", "SUCCEEDED", "FAILED", etc.

endpoint

string

API Gateway endpoint URL (null until deployment succeeds)

api_key_ids

array

Array of API key IDs created for this publication

Example Response

{
  "stage": "prod",
  "quota": {
    "limit": 10000,
    "offset": 0,
    "period": "MONTH"
  },
  "throttle": {
    "rate_limit": 10.0,
    "burst_limit": 20
  },
  "allowed_origins": [
    "https://app.example.com",
    "https://dashboard.example.com"
  ],
  "cfn_status": "CREATE_COMPLETE",
  "codebuild_id": "bedrock-chat-bot-publication:12345678",
  "codebuild_status": "SUCCEEDED",
  "endpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com/prod",
  "api_key_ids": ["key123", "key456"]
}

Notes

Returns 404 if the bot is not published
If CodeBuild has not succeeded, only codebuild_id, codebuild_status, and cfn_status will have values
Can be used by both owner and admin

Delete Bot Publication

Path Parameters

bot_id

string

required

The published bot ID to unpublish

Requirements

Bot must be published
CodeBuild must be completed (status must be "SUCCEEDED" or "FAILED")
Cannot delete while deployment is in progress

Create API Key

Path Parameters

bot_id

string

required

The published bot ID

Request Body

description

string

required

Description of the API key (e.g., purpose or application name)

Response

string

Unique API key identifier

description

string

API key description

value

string

The API key value (only returned on creation)

enabled

boolean

Whether the API key is enabled

created_date

integer

Unix timestamp of creation

Example Request

{
  "description": "Production web app key"
}

Example Response

{
  "id": "key_abc123xyz",
  "description": "Production web app key",
  "value": "sk_live_abcdefghijklmnopqrstuvwxyz123456789",
  "enabled": true,
  "created_date": 1704067200
}

Important: The API key value is only returned once during creation. Store it securely - you won’t be able to retrieve it again.

Get API Key

Path Parameters

bot_id

string

required

The published bot ID

api_key_id

string

required

The API key ID to retrieve

Response

Returns API key details (same structure as create response, but value is masked).

Delete API Key

Path Parameters

bot_id

string

required

The published bot ID

api_key_id

string

required

The API key ID to delete

Using Published Bot APIs

Once a bot is published, it gets its own API endpoint. Here’s how to use it:

Base URL

The base URL is returned in the publication endpoint:

https://{api-id}.execute-api.{region}.amazonaws.com/{stage}

Authentication

Include the API key in the request header:

x-api-key: sk_live_abcdefghijklmnopqrstuvwxyz123456789

Send Message

Request Body

conversation_id

string

Conversation ID (auto-generated if not provided)

message

object

required

Message object

Show message properties

content

array

required

Array of content objects (text, image, etc.)

model

string

required

Model to use (e.g., "claude-v3.5-sonnet")

continue_generate

boolean

default:"false"

Continue generation from last message

enable_reasoning

boolean

default:"false"

Enable reasoning mode

Response

conversation_id

string

The conversation identifier

message_id

string

The message ID for the response

Example Request

curl -X POST https://abcd1234.execute-api.us-east-1.amazonaws.com/prod/conversation \
  -H "x-api-key: sk_live_abcdefghijklmnopqrstuvwxyz123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": [
        {
          "content_type": "text",
          "body": "Hello, how can you help me?"
        }
      ],
      "model": "claude-v3.5-sonnet"
    }
  }'

Example Response

{
  "conversation_id": "01HQ4V8JFBK9PZXQ8YJKMND8GA",
  "message_id": "01HQ4V8JFBK9PZXQ8YJKMND8GB"
}

Async Processing: The message is queued for processing via SQS. Use the returned message_id to retrieve the response.

Get Conversation

Path Parameters

conversation_id

string

required

The conversation ID

Response

Returns the full conversation object with all messages (same structure as the main conversation API).

Get Specific Message

Path Parameters

conversation_id

string

required

The conversation ID

message_id

string

required

The message ID from the send message response

Response

conversation_id

string

The conversation identifier

message

object

The bot’s response message

create_time

float

Unix timestamp of conversation creation

Rate Limiting

Published APIs enforce the configured rate limits:

Quota Limits

Tracks total requests over a time period (DAY/WEEK/MONTH)
Returns HTTP 429 when quota is exceeded
Resets at the beginning of each period

Throttling

rate_limit: Maximum requests per second
burst_limit: Maximum concurrent requests
Returns HTTP 429 when throttle is exceeded

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1704067200

CORS Configuration

The allowed_origins setting controls which domains can access the API from browsers:

Specific origins: ["https://app.example.com", "https://dashboard.example.com"]
All origins: ["*"] (use with caution in production)

CORS headers are automatically included in responses:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, x-api-key

Best Practices

API Key Security
- Store API keys securely (environment variables, secrets manager)
- Never commit keys to version control
- Rotate keys periodically
- Use separate keys for different environments
Rate Limiting
- Set appropriate limits based on expected usage
- Monitor usage to adjust limits as needed
- Implement exponential backoff in client applications
CORS Configuration
- Specify exact origins in production (avoid *)
- Update origins when deploying to new domains
Monitoring
- Track API key usage
- Monitor rate limit violations
- Check CodeBuild deployment status
Deployment
- Wait for codebuild_status to be SUCCEEDED before using
- Use different stages for development and production
- Test with development keys before deploying

REST API

CDK API

​Overview

​Bot Publication Flow

​Publish Bot

​Path Parameters

​Request Body

​Requirements

​Example Request

​Get Bot Publication

​Path Parameters

​Response

​Example Response

​Notes

​Delete Bot Publication

​Path Parameters

​Requirements

​Create API Key

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Get API Key

​Path Parameters

​Response

​Delete API Key

​Path Parameters

​Using Published Bot APIs

​Base URL

​Authentication

​Send Message

​Request Body

​Response

​Example Request

​Example Response

​Get Conversation

​Path Parameters

​Response

​Get Specific Message

​Path Parameters

​Response

​Rate Limiting

​Quota Limits

​Throttling

​Rate Limit Headers

​CORS Configuration

​Best Practices

Build docs developers (and LLMs) love

Overview

Bot Publication Flow

Publish Bot

Path Parameters

Request Body

Requirements

Example Request

Get Bot Publication

Path Parameters

Response

Example Response

Notes

Delete Bot Publication

Path Parameters

Requirements

Create API Key

Path Parameters

Request Body

Response

Example Request

Example Response

Get API Key

Path Parameters

Response

Delete API Key

Path Parameters

Using Published Bot APIs

Base URL

Authentication

Send Message

Request Body

Response

Example Request

Example Response

Get Conversation

Path Parameters

Response

Get Specific Message

Path Parameters

Response

Rate Limiting

Quota Limits

Throttling

Rate Limit Headers

CORS Configuration

Best Practices