Oscar Chat API: Complete Developer Guide (2026)

What is the Oscar Chat API?

Oscar Chat is an AI-powered chatbot platform that lets businesses deploy intelligent chat widgets on their websites. The API extends this functionality by allowing programmatic control over your entire Oscar Chat infrastructure. You can manage workspaces, create and configure widgets, retrieve user account details, and much more — all through simple REST API calls.

The API follows RESTful conventions, uses JSON for all request and response bodies, and authenticates via token-based authentication embedded directly in the URL path. This makes it incredibly straightforward to integrate into any tech stack.

Getting Started: Authentication & Base URL

All Oscar Chat API requests are sent to a single base URL:

https://api.oscarchat.ai

Authentication is handled through a token embedded in the URL path. You can obtain your unique API token from the Oscar Chat Dashboard under your account settings. Every API request follows this pattern:

https://api.oscarchat.ai/{your-api-token}/endpoint

Important: Your API token is a secret credential. Never expose it in client-side JavaScript, public repositories, or any code that end users can inspect. Always make API calls from your server-side code.

API Endpoints Overview

The Oscar Chat API provides eight endpoints organized around three main resources: Users, Workspaces, and Widgets.

User Endpoint

GET /{token}/me — Retrieve your user profile including plan details, account limits, and feature flags. This is the perfect endpoint to verify your API token is working and to check what features your plan includes.

curl -X GET https://api.oscarchat.ai/YOUR_TOKEN/me

The response includes your user ID, email, name, plan information, and a detailed rules object that specifies your account limits (number of agents, workspaces, message counts, and feature access).

Workspace Endpoints

Workspaces are organizational containers for your widgets. Think of them as projects or folders.

GET /{token}/workspaces — List all your workspaces with pagination support. Use the page and limit query parameters to control results.

PUT /{token}/workspaces/{id} — Update a workspace name. Send a JSON body with the new name field.

Widget Endpoints

Widgets are the core of Oscar Chat — they’re the actual chatbot instances you deploy on websites.

GET /{token}/widgets — List all your widgets.
GET /{token}/widgets/{id} — Get a specific widget by ID.
POST /{token}/widgets/add — Create a new widget (requires name and workspace_id).
PUT /{token}/widgets/{id}/status — Toggle a widget active/inactive.
DELETE /{token}/widgets/{id} — Permanently delete a widget.

Practical Code Examples

Let’s look at real-world examples in multiple programming languages. These are production-ready snippets you can adapt for your projects.

JavaScript (Node.js / Browser)

const TOKEN = 'your-api-token';
const BASE = `https://api.oscarchat.ai/${TOKEN}`;

// Fetch all widgets
async function getWidgets() {
  const response = await fetch(`${BASE}/widgets`);
  const widgets = await response.json();
  return widgets;
}

// Create a new widget
async function createWidget(name, workspaceId) {
  const response = await fetch(`${BASE}/widgets/add`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, workspace_id: workspaceId })
  });
  return response.json();
}

// Toggle widget status
async function setWidgetStatus(widgetId, status) {
  const response = await fetch(`${BASE}/widgets/${widgetId}/status`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status }) // 'active' or 'inactive'
  });
  return response.json();
}

Python

import requests

TOKEN = "your-api-token"
BASE = f"https://api.oscarchat.ai/{TOKEN}"

# Get user profile and plan info
user = requests.get(f"{BASE}/me").json()
print(f"Plan: {user['plan_name']}, Expires: {user['plan_expiration_date']}")

# List workspaces with pagination
workspaces = requests.get(f"{BASE}/workspaces", params={"page": 1, "limit": 10}).json()
for ws in workspaces:
    print(f"Workspace: {ws['name']} (ID: {ws['id']})"  )

# Create a widget and activate it
new_widget = requests.post(f"{BASE}/widgets/add", json={
    "name": "Customer Support Bot",
    "workspace_id": workspaces[0]["id"]
}).json()
print(f"Created widget: {new_widget['id']}")

PHP

<?php
$token = 'your-api-token';
$base = "https://api.oscarchat.ai/$token";

// Get user info
$user = json_decode(file_get_contents("$base/me"), true);
echo "Plan: " . $user['plan_name'] . "\n";

// Create a widget using cURL
$ch = curl_init("$base/widgets/add");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'My New Bot',
        'workspace_id' => 1
    ]),
    CURLOPT_RETURNTRANSFER => true
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Widget created: " . $result['id'] . "\n";
?>

Data Models

Understanding the data structures the API returns is essential for building robust integrations.

The User object contains your account details: id, mail, first_name, last_name, plan_expiration_date, plan_name, and a nested rules object. The rules object defines your plan’s limits — how many agents, workspaces, and messages you can use, plus boolean flags for premium features like lead_magnet, ai_assistant, and all_in_one.

Workspaces are simple objects with id, name, description, created_at, and updated_at fields. They serve as organizational containers for your widgets.

Widgets have four fields: id, name, owner (your user ID), and status (either “active” or “inactive”). When a widget is active, it’s live and serving visitors on your website.

All errors follow a consistent format with a single error field containing a human-readable description.

Error Handling & Best Practices

The API uses standard HTTP status codes: 200 for success, 201 for created resources, 204 for successful deletions, 400 for bad requests, 401 for authentication failures, 404 for missing resources, and 429 for rate limiting.

When you encounter a 429 response, implement exponential backoff — wait 1 second, then 2, then 4, and so on before retrying. Rate limits vary by plan: Free accounts get 30 requests per minute, Pro gets 60, and Enterprise gets 120.

Always validate API responses before processing them. Check the HTTP status code first, then parse the JSON body. Handle errors gracefully to provide a good experience for your users.

Common Use Cases

Multi-site management: If you manage chatbots across multiple client websites, use the API to automate widget creation and status management from a central dashboard.

Automated deployment: Integrate widget creation into your CI/CD pipeline — automatically create and configure chatbots when deploying new websites.

Monitoring: Build health checks that verify your widgets are active and your account has sufficient message quota remaining.

Custom dashboards: Pull workspace and widget data into your own analytics platform or admin panel for a unified view of all your chatbot deployments.

Full Documentation

This guide covers the essentials, but for complete endpoint documentation with detailed parameter tables, response schemas, and more code examples, visit our full API documentation page.