Heppu API

Three nouns. Workforce, jobs, knowledge. Everything else is plumbing.

base urlhttps://v2.heppu.ai/api

The mental model

Heppu is not a bot builder. You hire a digital worker, hand it a job, and give it the knowledge it needs to do the job. The API follows the same three nouns as the dashboard.

Noun	What it is	Where to start
Workforce	The workers. Voice or chat agents with a name, a model and tools.	List workers
Jobs	Work assigned to a worker. Has contacts, runs executions, produces outcomes.	Add contacts
Knowledge	What the worker knows. Collections of sources you push and we index.	Push a source

Conversations (calls and chats) are what happens when a job runs. You can also poke them directly, see Chat and Calls.

Sixty second start

Make a key

Dashboard, Profile, API keys. Keys start with hep, expire in 30 days by default.

Find a worker

curl https://v2.heppu.ai/api/v2/agents -H "x-api-key: hep_..."

Give a job a contact

curl -X POST https://v2.heppu.ai/api/v2/jobs/JOB_ID/contacts \
  -H "x-api-key: hep_..." -H "Content-Type: application/json" \
  -d '{"contactPhone":"+358401234567","contactName":"Ada"}'

The job's worker picks the contact up on the next tick. Done.

Conventions

Base URL is https://v2.heppu.ai/api. Every path on this site is relative to that.

Two path prefixes exist. /v2 is the current one and also accepts a dashboard session. /v1 is older, key only, and still fully supported. Nothing is deprecated. Use whichever has the endpoint you need.

JSON in, JSON out. Success looks like this:

{ "data": { }, "meta": { "timestamp": "2026-09-11T10:00:00.000Z" } }

Errors look like this. Timestamps are ISO 8601. Phone numbers are E.164 (+358...). IDs are UUIDs unless we say otherwise.

Everything is scoped to the organization the key belongs to. There is no way to ask for another org's data, so you don't need to pass an org id anywhere.

For your AI agent

/llms.txt is an index, /llms-full.txt is every page in one file, /llms.mdx/<path> is one page as markdown. Point Claude, Cursor or whatever you use at those instead of scraping HTML.