API overview and authentication

One base URL, three authentication personas, and a small set of conventions that hold across every endpoint.

On this page

Base URL
The three keys
Managing your API key
Conventions
OpenAPI specification

Base URL

https://api.oyechats.com

Everything is JSON in and JSON out, except file uploads (multipart) and CSV exports. HTTPS only. The API is versionless today; breaking changes are announced on the changelog before they ship.

The three keys

Header	Who it represents	Where it comes from
`X-API-Key`	Your workspace. Full read and write across chatbots, knowledge, leads, analytics and billing.	Workspace → API Keys in the dashboard.
`X-Bot-Key`	A website visitor talking to one chatbot. Can start and continue conversations, nothing else.	The `data-bot-key` in your embed snippet. Public.
`X-Operator-Key`	One live-chat operator. Scoped to the conversations they may handle.	Issued to the operator when their account is created.

curl

curl https://api.oyechats.com/bots \
  -H "X-API-Key: $OYECHATS_API_KEY"

Never ship X-API-Key to a browser. It is a full-access workspace credential. Call the API from your server. Anything a browser needs to do, the widget already does with the public bot key.

Managing your API key

Read it from Workspace → API Keys.
Rotate it from the same screen. Rotation is immediate. The old key stops working the moment the new one is issued, so update your integrations first.
Store it in a secret manager or an environment variable. Not in source control, not in a front-end bundle, not in a support ticket.
If it leaks, rotate it. There is no partial revocation.

Conventions

Scoping: Every workspace-authenticated response is scoped to your workspace on the server. Passing another workspace's bot_id returns 403, not someone else's data.
Pagination: List endpoints take page and limit, or limit and offset. Defaults are modest (typically 50) and each endpoint enforces its own maximum.
Filtering: Most list endpoints accept bot_id to narrow to one chatbot, and a date or days window where it makes sense.
Timestamps: ISO 8601 with an explicit UTC offset.
Money: Integer minor units. Paise for INR, cents for USD, with the currency alongside. Never a float.
Identifiers: Chatbots have both a numeric bot_id (used by the API) and a public bot_key (used by the widget). Conversations are identified by session_id.

OpenAPI specification

The full machine-readable schema for the customer-facing API (every parameter, request body and response model) is published as OpenAPI. Import it into Postman, Insomnia, or a client generator.

Specification URL

https://www.oyechats.com/openapi.json

Customer surface only. The published specification deliberately excludes internal administrative and platform-operations endpoints. If a route is not in the specification, treat it as unsupported and subject to change without notice.

Something here wrong or missing? Tell us and name this page. We will fix it.