Getting started with the ContextGPT API

The ContextGPT API allows you to programmatically manage chatbots, send messages, access conversation history, and configure settings. All endpoints use REST principles and return JSON responses.

This page documents the legacy /api/v1 API. For new integrations, use API Reference → v2 from the version selector.

Base URL

All API requests are made to:

https://ContextGPT.in/api/v1

Authentication

ContextGPT uses API keys for authentication. Include your API key in the Authorization header of every request.

Getting your API key

Sign in to your ContextGPT account
Navigate to Billing or Profile > API Access
Copy your API key
Store it securely (never commit to version control)

Keep your API key secure. Anyone with your key can access and modify your chatbots.

Using your API key

Include your API key in the Authorization header with the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Example request

curl https://ContextGPT.in/api/v1/chatbots \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication errors

401 — Missing or invalid API key
403 — Plan doesn't include API access

{
  "success": false,
  "message": "Authorization header does not contain a valid API key"
}

{
  "success": false,
  "message": "API access is not available on your current plan. Please upgrade to access this feature."
}

Response format

All API responses use a consistent JSON structure:

Success response
Error response

{
  "statusCode": 200,
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

{
  "success": false,
  "message": "Error message"
}

When the error includes validation details, an errors array is also present:

{
  "success": false,
  "message": "Request body is not valid",
  "errors": [
    {
      "path": ["fieldName"],
      "message": "Required"
    }
  ]
}

Error handling

HTTP status codes

200 OK - Request succeeded
400 Bad Request - Invalid request parameters or body
401 Unauthorized - Missing or invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn’t exist
405 Method Not Allowed - HTTP method not supported
500 Internal Server Error - Server error

Common error codes

API_KEY_NOT_VALID - Invalid or missing API key
REQUEST_VALIDATION_FAILED - Request body validation failed
CHATBOT_NOT_FOUND - Chatbot doesn’t exist
CHATBOT_FETCH_FORBIDDEN - No permission to access chatbot
CHATBOT_LIMIT_REACHED - Exceeded chatbot quota
MESSAGES_LIMIT_REACHED - Exceeded message quota

Validation errors

When request validation fails, the errors array contains specific field errors:

{
  "success": false,
  "message": "Request body is not valid",
  "errors": [
    {
      "path": ["chatbotName"],
      "message": "Required"
    }
  ]
}

Rate limiting

API requests are rate-limited at multiple levels to ensure platform stability and fair usage.

Generic API limits

All requests are subject to these limits regardless of plan (to make platform accessible to all users):

Limit	Value	Scope
Per IP	100 req/sec	Applied globally before authentication —
Per user	500 req/60s	Applied after authentication on all endpoints
Concurrency	10 simultaneous	Upload/ingestion endpoints only

AI & messaging limits

Requests that trigger AI responses have additional per-plan limits:

Plan	Messages/min	AI replies/min
Starter	600	150
Growth	3,000	750
Scale	12,000	3,000

Monthly message quotas are also enforced per plan. When the monthly quota is exhausted, further requests return 429 with MESSAGES_LIMIT_REACHED.

Rate limit response

When you exceed any rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header:

{
  "success": false,
  "message": "Rate limit exceeded. Too many requests — please wait before trying again.",
  "retryAfter": 45,
  "limit": 500,
  "remaining": 0,
  "windowSeconds": 60
}

Pagination

List endpoints support pagination using query parameters:

GET /v1/chatbots?page=1&limit=20

Parameters:

page - Page number (default: 1)
limit - Results per page (default: 20, max: 100)

Paginated responses include metadata:

{
  "success": true,
  "message": "Fetched chatbots successfully",
  "data": {
    "chatbots": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

Making requests

curl -X POST https://ContextGPT.in/api/v1/chatbots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotName": "My New Chatbot"
  }'

Common workflows

Creating and configuring a chatbot

Create chatbot

POST /v1/chatbots/account/{accountId}/create-chatbot

Update appearance

PUT /v1/chatbots/chatbot/{chatbotId}/appearance

Add conversation starters

POST /v1/chatbots/chatbot/{chatbotId}/conversation-starters

Configure settings

PUT /v1/chatbots/chatbot/{chatbotId}/settings

Add instructions or persona

POST /v1/chatbots/chatbot/{chatbotId}/instructions

Sending messages

Create thread

POST /v1/chatting/{chatbotId}/threads

Send message

POST /v1/chatting/{chatbotId}/thread/{threadId}/message

Fetch response

Included in send message response

Update reaction

PATCH /v1/chatting/{chatbotId}/message/{messageId}

Managing conversations

Fetch all threads

GET /v1/chatting/{chatbotId}/threads

Get thread details

GET /v1/chatting/{chatbotId}/thread/{threadId}

Get thread messages

GET /v1/chatting/{chatbotId}/thread/{threadId}/messages

Escalate to agent

POST /v1/chatting/{chatbotId}/thread/{threadId}/escalate

Update thread

PATCH /v1/chatting/{chatbotId}/thread/update-thread

API resources

The ContextGPT API provides endpoints for:

Chatbots - Create, read, update, delete chatbots
Appearance - Customize chatbot visual design
Conversation Starters - Manage conversation starter prompts
Follow-up Prompts - Post-response suggestions
Instructions - Manage chatbot instruction sets
Personas - Manage chatbot personas
Localization - Configure locale-specific settings
Lead Settings - Configure lead capture behavior
Human Support Settings - Configure escalation and handoff
Settings - Configure general chatbot behavior
Messages - Send and receive messages
Threads - Manage conversation threads
Text Snippets - Manage reusable text content

Best practices

Security
Performance
Error handling
Data management

Never expose API keys - Keep them server-side only

Use environment variables - Don’t hardcode keys

Rotate keys regularly - Generate new keys periodically

Limit key scope - Use separate keys for different environments

Check success field - Always verify success: true

Log error codes - Track error patterns

Retry transient errors - Retry 500 errors with backoff

Validate before sending - Reduce 400 errors

Webhooks

Instead of polling the API, use webhooks to receive real-time updates:

New messages
Lead captures
Conversation escalations
Custom events

Configure webhooks in your chatbot settings or via the API. See Chatbot Settings - Advanced for webhook configuration.

SDKs and libraries

Official SDKs

Currently, ContextGPT doesn’t provide official SDKs. Use standard HTTP libraries in your language of choice.

Community libraries

Check our community forum for user-contributed libraries and wrappers.

Support

Need help with the API?

Documentation - Browse the API reference
Email - support@ContextGPT.in
Community - Join our Slack or forum
Enterprise - Dedicated support for enterprise customers

Next steps

Chatbot endpoints

Create and manage chatbots programmatically

Messages

Send messages and handle conversations

Settings

Configure chatbot behavior via API

Threads

Manage conversation threads

​Base URL

​Authentication

​Getting your API key

​Using your API key

​Example request

​Authentication errors

​Response format

​Error handling

​Validation errors

​Rate limiting

​Generic API limits

​AI & messaging limits

​Rate limit response

​Pagination

​Making requests

​Common workflows

​API resources

​Best practices

​Webhooks

​SDKs and libraries

​Official SDKs

​Community libraries

​Support

​Next steps

Chatbot endpoints

Messages

Settings

Threads

Base URL

Authentication

Getting your API key

Using your API key

Example request

Authentication errors

Response format

Error handling

Validation errors

Rate limiting

Generic API limits

AI & messaging limits

Rate limit response

Pagination

Making requests

Common workflows

API resources

Best practices

Webhooks

SDKs and libraries

Official SDKs

Community libraries

Support

Next steps