API Reference

API reference — overview

The HeyMello REST API lets developers do everything the dashboard does: create agents, place calls, run campaigns, and pull results — programmatically. Use it to integrate voice agents into your own product and sync data with your systems.

New to HeyMello? Start with the product docs. The API is for developers building custom integrations.

Base URL

https://<your-heymello-api-host>/api/v1

All endpoints are versioned under /api/v1. Your account team will give you the exact host for your environment.

Authentication

The API uses bearer tokens. Log in to get an access token, then send it on every request:

Authorization: Bearer <access_token>

See Authentication for the full flow (including MFA).

Conventions


Format	JSON request and response bodies.
HTTP methods	`GET` (read), `POST` (create/actions), `PUT`/`PATCH` (update), `DELETE` (remove).
IDs	Resources are identified by unique IDs returned when you create them.
Pagination	List endpoints accept `limit` and `offset` (and often filters).
Dates	ISO 8601 timestamps; analytics accept a `days` window or explicit `start_date`/`end_date`.
Multi-tenancy	Every request is scoped to your organization. You can only access your own data.

Errors

The API uses standard HTTP status codes:

Code	Meaning
`200` / `201`	Success.
`400`	Bad request — check your parameters.
`401`	Missing or invalid token — re-authenticate.
`403`	Authenticated, but not allowed (role or verification required).
`404`	Resource not found.
`409`	Conflict (e.g. duplicate).
`422`	Validation error — a field is missing or malformed.
`5xx`	Something went wrong on our side.

Error responses include a message describing what went wrong.

Endpoint groups

The API is organized by domain. See these reference pages:

Authentication — login, MFA, signup, password reset.
Core endpoints — agents, voices, calls, phone numbers, campaigns, knowledge base, tools, bookings, analytics, billing, and more.

A quick example

# 1. Authenticate
curl -X POST "$BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••••••"}'
# → { "access_token": "…", "token_type": "bearer" }

# 2. List your agents
curl "$BASE/agents/" \
  -H "Authorization: Bearer $TOKEN"

# 3. Place an outbound call
curl -X POST "$BASE/calls/make-call" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"…","to_number":"+44…","first_name":"Alex"}'

Next: Authentication →