Developer

API Documentation

Integrate BotDeck into your applications with our REST API

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer bdk_YOUR_API_KEY

Permissions

Scopes available for API keys

bots:readList and view your bots

bots:writeCreate and update bots

bots:chatSend messages to bots and compare

conversations:readList and view conversations

prompts:readList prompt templates

prompts:writeCreate and update prompts

deckflows:readList your deckflows

deckflows:executeExecute deckflows

analytics:readView usage and analytics

webhooks:readList and manage webhooks

webhooks:writeCreate and update webhooks

Endpoints

Base URL:https://www.botdeck.ai

GET/api/v1/bots

List all your bots

Required permission:bots:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  https://www.botdeck.ai/api/v1/bots

Response Example

{
  "data": [
    {
      "id": 1,
      "name": "My Bot",
      "model": "gpt-4o",
      "provider": "openai",
      "category": "general"
    }
  ]
}

GET/api/v1/bots/:id

Get a specific bot by ID

Required permission:bots:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  https://www.botdeck.ai/api/v1/bots/1

Response Example

{
  "data": {
    "id": 1,
    "name": "My Bot",
    "model": "gpt-4o",
    "provider": "openai",
    "systemPrompt": "You are a helpful assistant.",
    "category": "general"
  }
}

POST/api/v1/bots/:id/chat

Send a message to a bot and get a response

Required permission:bots:chat

cURL Example

curl -X POST -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, how are you?"}' \
  https://www.botdeck.ai/api/v1/bots/1/chat

Request Body

{
  "message": "Hello, how are you?"
}

Response Example

{
  "data": {
    "content": "I'm doing well! How can I help you today?",
    "tokensUsed": {
      "prompt": 25,
      "completion": 12,
      "total": 37
    }
  }
}

GET/api/v1/deckflows

List all your deckflows (workflows)

Required permission:deckflows:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  https://www.botdeck.ai/api/v1/deckflows

Response Example

{
  "data": [
    {
      "id": 1,
      "name": "Content Pipeline",
      "description": "Generate and refine content",
      "status": "active"
    }
  ]
}

POST/api/v1/deckflows/:id/execute

Execute a deckflow with the given input

Required permission:deckflows:execute

cURL Example

curl -X POST -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Write a blog post about AI"}' \
  https://www.botdeck.ai/api/v1/deckflows/1/execute

Request Body

{
  "input": "Write a blog post about AI"
}

Response Example

{
  "data": {
    "runId": 42,
    "status": "completed",
    "output": "Here is your blog post about AI...",
    "totalTokens": 1250,
    "durationMs": 8500
  }
}

GET/api/v1/usage

Get your usage summary for the past N days

Required permission:analytics:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  "https://www.botdeck.ai/api/v1/usage?days=30"

Response Example

{
  "data": {
    "totalTokens": 45000,
    "totalCost": "2.25",
    "dailyBreakdown": [
      {
        "date": "2026-03-10",
        "tokens": 15000,
        "cost": "0.75"
      }
    ]
  }
}

POST/api/v1/bots

Create a new bot with the specified configuration

Required permission:bots:write

cURL Example

curl -X POST -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "model": "gpt-4o", "systemPrompt": "You are helpful."}' \
  https://www.botdeck.ai/api/v1/bots

Request Body

{
  "name": "My Assistant",
  "model": "gpt-4o",
  "provider": "openai",
  "systemPrompt": "You are a helpful assistant.",
  "category": "general"
}

Response Example

{
  "data": {
    "id": 42,
    "name": "My Assistant",
    "model": "gpt-4o",
    "status": "active",
    "createdAt": "2026-03-13T10:00:00Z"
  }
}

GET/api/v1/conversations

List all conversations with pagination and filtering

Required permission:conversations:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  "https://www.botdeck.ai/api/v1/conversations?page=1&limit=20"

Response Example

{
  "data": [
    {
      "id": 1,
      "botId": 5,
      "title": "Code Review",
      "messageCount": 12,
      "createdAt": "2026-03-12T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 45
  }
}

GET/api/v1/conversations/:id/messages

Get all messages in a conversation

Required permission:conversations:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  https://www.botdeck.ai/api/v1/conversations/1/messages

Response Example

{
  "data": [
    {
      "id": 1,
      "role": "user",
      "content": "Hello!",
      "createdAt": "2026-03-12T08:01:00Z"
    },
    {
      "id": 2,
      "role": "assistant",
      "content": "Hi! How can I help?",
      "createdAt": "2026-03-12T08:01:02Z"
    }
  ]
}

POST/api/v1/prompts

Create a new prompt template

Required permission:prompts:write

cURL Example

curl -X POST -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Code Review", "content": "Review this code..."}' \
  https://www.botdeck.ai/api/v1/prompts

Request Body

{
  "title": "Code Review",
  "content": "Review this code for bugs and improvements: {{code}}",
  "botType": "coding",
  "tags": [
    "code",
    "review"
  ]
}

Response Example

{
  "data": {
    "id": 15,
    "title": "Code Review",
    "status": "active",
    "createdAt": "2026-03-13T10:00:00Z"
  }
}

GET/api/v1/prompts

List all your prompt templates with optional bot-type filtering

Required permission:prompts:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  "https://www.botdeck.ai/api/v1/prompts?botType=coding"

Response Example

{
  "data": [
    {
      "id": 15,
      "title": "Code Review",
      "botType": "coding",
      "usageCount": 42,
      "rating": 4.8
    }
  ]
}

POST/api/v1/bots/compare

Send the same prompt to multiple bots and compare responses

Required permission:bots:chat

cURL Example

curl -X POST -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"botIds": [1, 2, 3], "prompt": "Explain quantum computing"}' \
  https://www.botdeck.ai/api/v1/bots/compare

Request Body

{
  "botIds": [
    1,
    2,
    3
  ],
  "prompt": "Explain quantum computing in simple terms"
}

Response Example

{
  "data": {
    "results": [
      {
        "botId": 1,
        "botName": "GPT-4o Bot",
        "response": "Quantum computing uses...",
        "tokensUsed": 150,
        "durationMs": 2300
      }
    ]
  }
}

GET/api/v1/webhooks

List configured webhooks for real-time event notifications

Required permission:webhooks:read

cURL Example

curl -H "Authorization: Bearer bdk_YOUR_API_KEY" \
  https://www.botdeck.ai/api/v1/webhooks

Response Example

{
  "data": [
    {
      "id": 1,
      "url": "https://example.com/webhook",
      "events": [
        "bot.message",
        "conversation.created"
      ],
      "active": true
    }
  ]
}

Rate Limits

API rate limits per key

100

Requests / minute

10,000

Requests / day

5 MB

Max request body

Error Codes

Common HTTP status codes returned by the API

200OKRequest succeeded

400Bad RequestInvalid or missing parameters

401UnauthorizedMissing or invalid API key

403ForbiddenInsufficient permissions for this endpoint

404Not FoundResource not found or not owned by you

429Too Many RequestsRate limit exceeded

500Internal ErrorServer error, please retry

SDK & Language Examples

Quick integration snippets for popular languages

// Install: npm install botdeck-sdk
import BotDeck from 'botdeck-sdk';

const client = new BotDeck({ apiKey: 'bdk_YOUR_API_KEY' });

// List your bots
const bots = await client.bots.list();
console.log(bots);

// Chat with a bot
const response = await client.bots.chat(1, {
  message: 'Hello, how are you?'
});
console.log(response.content);

// Compare bots
const comparison = await client.bots.compare({
  botIds: [1, 2, 3],
  prompt: 'Explain quantum computing'
});
comparison.results.forEach(r => {
  console.log(r.botName, r.response);
});

Quickstart Guide

Get up and running in under 5 minutes

Create an API Key

Go to API Keys in the sidebar and generate a new key with the permissions you need.

Create a Bot

Use the Bot Builder or the POST /api/v1/bots endpoint to create your first bot with a system prompt.

Send a Message

Use POST /api/v1/bots/:id/chat to send a message and receive an AI response.

Build a Deckflow

Chain multiple bots together using Deckflows for complex multi-step workflows.

Monitor Usage

Track your token usage and costs with the GET /api/v1/usage endpoint.

Webhooks

Receive real-time notifications for events in your account

Configure webhooks to receive HTTP POST callbacks when events occur. Available events:

bot.messageNew message sent or received

bot.createdA new bot was created

conversation.createdA new conversation started

conversation.archivedA conversation was archived

deckflow.completedA deckflow run finished

deckflow.failedA deckflow run failed

subscription.updatedSubscription plan changed

usage.thresholdUsage threshold reached

// Webhook payload example
{
  "event": "bot.message",
  "timestamp": "2026-03-13T10:00:00Z",
  "data": {
    "botId": 1,
    "conversationId": 42,
    "message": {
      "role": "assistant",
      "content": "Here is your response..."
    }
  }
}