Skip to content
Documentation

Reference

API reference

Every endpoint the platform publishes, grouped by the plugin that owns it. Mobile clients use exactly this surface — there is no separate web API.

Conventions

  • Base URL is https://api.shubham.ai/v1. The version is in the path.
  • All requests and responses are JSON. Send Content-Type: application/json.
  • Authentication is a bearer token: Authorization: Bearer sk_live_….
  • Money is always in minor units as an integer — paise, cents. There are no floats anywhere in the API, because a rounding error on an invoice is not a rounding error to the customer.
  • Timestamps are ISO 8601 in UTC.
  • Every response carries X-Request-Id. Quote it when contacting support.

Errors

Errors use a consistent shape with a stable machine-readable code.

json
{
  "error": {
    "code": "permission_denied",
    "message": "This key does not hold campaign.send.",
    "requestId": "req_01J8ZK4M2Q",
    "docs": "https://shubham.ai/docs/api#errors"
  }
}
CodeStatusMeaning
invalid_request400The request shape or a parameter value is wrong.
unauthenticated401Missing, malformed or revoked API key.
permission_denied403The key is valid but lacks the required permission.
not_found404No such resource in this tenant. Never leaks whether it exists elsewhere.
conflict409The resource changed since you read it. Re-read and retry.
plan_limit_reached422A plan quota would be exceeded by this request.
rate_limited429Too many requests. Honour the Retry-After header.
provider_error502An upstream provider failed. Safe to retry with backoff.

Pagination

List endpoints are cursor-paginated. Cursors are opaque — do not parse them. Offset pagination is not offered because it produces duplicates and gaps on data that is changing while you page through it.

http
GET /v1/contacts?limit=50&cursor=eyJpZCI6ImNudF80ODIwIn0

{
  "data": [ /* … */ ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6ImNudF80OTAxIn0",
    "total": 41208
  }
}

Rate limits

Defaults are 600 reads and 120 writes per minute per key, and you can set a lower ceiling per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 always includes Retry-After in seconds — honour it rather than retrying immediately.

Endpoints

Grouped by the plugin that publishes them. An endpoint only exists for a tenant that has the owning plugin enabled — calling one you do not hold returns permission_denied, not not_found.

Authentication

core.authCore
  • POST/v1/auth/loginExchange credentials for a session token.public
  • POST/v1/auth/refreshRefresh an access token.public
  • POST/v1/auth/2fa/verifyVerify a two-factor challenge.public

Team Management

core.teamCore
  • GET/v1/team/membersList team members.team.view
  • POST/v1/team/invitesInvite a team member.team.manage

Billing & Subscriptions

core.billingCore
  • GET/v1/billing/subscriptionCurrent subscription and limits.billing.view
  • GET/v1/billing/invoicesList invoices.billing.view
  • GET/v1/billing/walletWallet balances by channel.wallet.view

WhatsApp Cloud API

channel.whatsapp_cloudChannels
  • GET/v1/channels/whatsapp/numbersList connected numbers with health.channel.view
  • POST/v1/channels/whatsapp/messagesSend a message.inbox.reply
  • GET/v1/whatsapp/numbersList connected WhatsApp numbers.channel.view
  • GET/v1/whatsapp/numbers/:idGet a connected number.channel.view
  • GET/v1/messagesList messages.inbox.view
  • POST/v1/messagesSend a WhatsApp message (text / template / media).inbox.reply
  • GET/v1/messages/:idGet a message.inbox.view

Shared Team Inbox

channel.inboxChannels
  • GET/v1/inbox/conversationsList conversations with filters.inbox.view
  • POST/v1/inbox/conversations/:id/assignAssign a conversation.inbox.assign
  • GET/v1/conversationsList conversations.inbox.view
  • GET/v1/conversations/:idGet a conversation.inbox.view
  • GET/v1/conversations/:id/messagesList a conversation's messages.inbox.view
  • POST/v1/conversations/:id/messagesSend a reply in a conversation.inbox.reply

Broadcast & Campaigns

growth.broadcastGrowth
  • GET/v1/campaignsList campaigns.campaign.view
  • POST/v1/campaignsCreate a campaign.campaign.create
  • GET/v1/campaigns/:idGet a campaign.campaign.view
  • POST/v1/campaigns/:id/scheduleSchedule a campaign.campaign.send
  • POST/v1/campaigns/:id/pausePause a campaign.campaign.send
  • POST/v1/campaigns/:id/resumeResume a campaign.campaign.send
  • POST/v1/campaigns/:id/cancelCancel a campaign.campaign.send
  • POST/v1/campaigns/:id/retryRetry failed recipients.campaign.send

Templates

growth.templatesGrowth
  • GET/v1/templatesList templates.template.view
  • POST/v1/templatesCreate a template draft.template.manage
  • GET/v1/templates/:idGet a template.template.view

Contacts

crm.contactsCRM
  • GET/v1/contactsList contacts with filters and pagination.contact.view
  • POST/v1/contactsCreate a contact.contact.manage
  • GET/v1/contacts/:idGet a contact.contact.view
  • PUT/v1/contacts/:idUpdate a contact.contact.manage
  • DELETE/v1/contacts/:idDelete a contact.contact.manage
  • POST/v1/contacts/importBulk import.contact.import

Analytics

insights.analyticsData
  • GET/v1/analytics/overviewAnalytics overview (messages, campaigns, contacts, wallet).analytics.view
  • GET/v1/analytics/messagesDaily message volume time series.analytics.view
  • GET/v1/analytics/campaignsPer-campaign counters and rollup.analytics.view

Public API

dev.apiDeveloper
  • GET/v1/keysList API keys.api_key.view
  • POST/v1/keysIssue an API key.api_key.manage
  • DELETE/v1/keys/:idRevoke an API key.api_key.manage

Webhook Engine

dev.webhooksDeveloper
  • GET/v1/webhooksList webhooks.webhook.manage
  • POST/v1/webhooksCreate a webhook endpoint.webhook.manage
  • DELETE/v1/webhooks/:idDelete a webhook.webhook.manage

Webhook events

Subscribe to any of these under Settings → Developers → Webhooks. Every delivery is signed; verify the signature before trusting the body.

Billing & Subscriptions

invoice.issuedwallet.creditedwallet.debitedsubscription.changed

WhatsApp Cloud API

channel.connectedchannel.disconnectedchannel.health_changedmessage.deliveredmessage.failed

Embedded Signup

channel.connected

QR Session (Unofficial)

channel.connectedchannel.disconnected

Shared Team Inbox

conversation.startedconversation.assignedconversation.resolved

Broadcast & Campaigns

campaign.scheduledcampaign.sent

Templates

template.status_changed

Forms & Lead Capture

lead.created

Flow Builder

workflow.startedworkflow.completedworkflow.failed

Automation Rules

automation.triggered

AI Agents

ai.response_generatedai.tool_invoked

Contacts

contact.createdcontact.imported

Leads & Pipeline

lead.createdlead.stage_changeddeal.wondeal.lost

Payments

payment.completedpayment.failed

Invoices

invoice.issued

Tenant Management

tenant.createdtenant.suspendedtenant.reactivatedtenant.impersonation_startedtenant.impersonation_ended

Plugin Marketplace

plugin.installedplugin.enabledplugin.disabledplugin.upgraded

Plans & Pricing

subscription.changed

Credits & Wallet Ops

wallet.creditedwallet.debited

This reference is generated from the plugin registry, which is why it cannot document an endpoint the product does not publish. If something is missing here, it does not exist yet.