API Overview

The OliAI Public API provides programmatic access to contacts, audiences, campaigns, and voice flows. It is designed for integrating OliAI into your own applications and workflows.

Base URLs

Environment	Base URL
Production	`https://api.oliai.in/v1`
QA / Staging	`https://api.qa.oliai.in/v1`

Authentication

All API requests require an API key passed in the x-api-key header:

x-api-key: sk_live_your_key_here

See Authentication for details on obtaining and managing API keys.

Request Format

All request bodies must be JSON with Content-Type: application/json
Phone numbers must be in E.164 format (e.g., +919876543210)
Dates must be in ISO 8601 format (e.g., 2026-03-15T10:00:00Z)

Response Format

All responses are JSON. Successful responses return 200 or 201. Errors follow this structure:

{
  "statusCode": 400,
  "message": "phoneNumber must be a valid E.164 phone number",
  "error": "Bad Request"
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`limit`	integer	`20`	Items per page (max 100)

Paginated responses include:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

HTTP Status Codes

Code	Meaning
`200`	OK — request succeeded
`201`	Created — resource created successfully
`400`	Bad Request — validation error, check the message
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource does not exist or not in your organization
`409`	Conflict — resource already exists (e.g., duplicate phone number)
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — contact support

Rate Limiting

The API enforces rate limits per API key:

General endpoints: 60 requests/minute
Bulk import: 10 requests/minute

When rate limited, the response includes a Retry-After header indicating when you can retry.

Available Resources

Resource	Description
Contacts	Manage individual contact records
Audiences	Manage contact groups
Campaigns	Create and manage calling campaigns
Voice Flows	List available voice flows
Imports	Bulk data import via API

Admin Authentication