Skip to main content

Introduction

Welcome to the AskBenny API documentation. This guide covers the core entities in the system and how to interact with them through the REST API.

API Endpoints​

EnvironmentBase URL
Productionhttps://api.askbenny.ca
Developmenthttps://api-dev.askbenny.ca

Authentication​

Requests must include an API key in the x-api-key header (the only exception is the health check GET /v1):

curl -H "x-api-key: YOUR_API_KEY" https://api.askbenny.ca/v1/organizations

Send the key exactly as it was issued (sk_production_...), with no quotes, backticks, Bearer prefix, or spaces. A missing, malformed, revoked, or expired key returns 400 Bad Request with the message Invalid or expired API key; the response never repeats the key you sent.

Each API key is scoped to the organization it was created for (plus any organizations it provisioned through POST /v1/users and POST /v1/organizations). A request for any other organization's resources returns 401 Unauthorized, and a request for a user outside that scope returns 404 Not Found.

Rate Limits​

Each API key can make 300 requests per minute, counted across every endpoint. Requests over the limit return 429 Too Many Requests with the code API_KEY_RATE_LIMITED and a Retry-After header giving the seconds until the next minute starts; wait that long, then retry.

To stay well under the limit, use SMS webhooks to hear about new messages instead of polling GET /v1/organizations/{organizationId}/sms-logs.

Core Entities​

The API is built around the Organization — the business entity everything else belongs to:

Organization → has → Agents (each with its own Knowledge Base), Call Logs, SMS Logs, Batch Calls, Batch SMS

EntityDescription
OrganizationsBusiness entities that own agents, call logs, SMS logs, and campaigns
AgentsAI virtual assistants configured to handle calls and SMS for an organization; each agent owns its knowledge base
Knowledge BaseCollections of information stored on an agent that it references to answer customer inquiries
Call LogsRecords of all voice calls handled by agents, including transcripts and recordings
SMS LogsRecords of all SMS conversations handled by agents, including message threads

How They Connect​

Everything starts with your organization. An organization owns agents; each agent owns a knowledge base it uses to provide intelligent responses on calls and SMS conversations. Voice interactions are recorded as call logs, and text message conversations are recorded as SMS logs. Batch call and batch SMS campaigns produce entries in those same logs.

Next Steps​