1. Get a key
Sign in to the console and copy a test key from Developers. Test keys start with hp_test_ and are free. Live keys start with hp_live_ and are billed only when a task succeeds.
export HAPTI_KEY=hp_test_...2. Install a library
# Nothing to installnpm install hapti-sdkpip install hapti3. Run a task
The simplest way is to create the task and wait for its end. The libraries follow the task live and return as soon as it is over.
curl https://api.hapti.dev/v1/tasks \
-H "Authorization: Bearer $HAPTI_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://en.wikipedia.org", "goal": "Find the year Ada Lovelace was born."}'import Hapti from 'hapti-sdk';
const hapti = new Hapti(process.env.HAPTI_KEY);
const task = await hapti.tasks.run({
url: 'https://en.wikipedia.org',
goal: 'Find the year Ada Lovelace was born.',
});
console.log(task.status, task.result.answer);import os
from hapti import Hapti
hapti = Hapti(os.environ["HAPTI_KEY"])
task = hapti.tasks.run({
"url": "https://en.wikipedia.org",
"goal": "Find the year Ada Lovelace was born.",
})
print(task["status"], task["result"]["answer"])With cURL, the answer is the task at the moment it was created. Ask for it again with its id until status is final:
curl https://api.hapti.dev/v1/tasks/tsk_... -H "Authorization: Bearer $HAPTI_KEY"4. Answer the agent
The agent never invents a value. When something is missing, such as a code received by text message, the task goes to waiting with a pending question. Answer it and the agent goes on.
const task = await hapti.tasks.run(
{ url: 'https://bank.example.com', goal: 'Download my last statement.', user: 'customer_42' },
{ onWaiting: async (pending) => askTheCustomer(pending.text) },
);task = hapti.tasks.run(
{"url": "https://bank.example.com", "goal": "Download my last statement.", "user": "customer_42"},
on_waiting=lambda pending, task: ask_the_customer(pending["text"]),
)curl https://api.hapti.dev/v1/tasks/tsk_.../answer \
-H "Authorization: Bearer $HAPTI_KEY" \
-H "Content-Type: application/json" \
-d '{"key": "sms_code", "value": "482913"}'A waiting task looks like this:
{
"id": "tsk_9a96d9052acef545",
"object": "task",
"batch": null,
"schedule": null,
"mode": "test",
"status": "waiting",
"paused": null,
"level": "standard",
"price_cents": 0,
"starting_price_cents": 10,
"billed": false,
"user": "customer_42",
"url": "https://portal.example.com/claims",
"goal": "Declare the water damage claim and give me the claim number.",
"input": {
"data": {
"contract": "AX-4471",
"date": "2026-11-20"
},
"files": []
},
"pending": {
"type": "question",
"key": "policy_holder_phone",
"text": "Which phone number should the insurer call?",
"action_url": "https://api.hapti.dev/act/tsk_9a96d9052acef545.On4C9kUiLXVgYLsS.N4ex1GucyaH4OW-rayZGGJ3y6XzF7_fE"
},
"learn": true,
"used_recipe": null,
"template": null,
"created_by": {
"type": "key",
"id": "key_d160ed300d0cf627",
"hint": "hp_test_7eF…ZD9D",
"name": "default test key",
"owner_email": null
},
"recipe_chosen": null,
"recipe": null,
"dispute": null,
"result": null,
"files": [],
"usage": null,
"created_at": "2026-11-22T18:40:56.170Z",
"finished_at": null
}pending.action_url is a page where the person can answer by themselves, without an account. Send it to them by email or text message when you prefer not to relay the answer.
5. Read the result
A finished task carries the answer, the structured data when you gave an output schema, the files the site gave and what was billed.
{
"id": "tsk_9a96d9052acef545",
"object": "task",
"batch": null,
"schedule": null,
"mode": "test",
"status": "succeeded",
"paused": null,
"level": "standard",
"price_cents": 0,
"starting_price_cents": 10,
"billed": false,
"user": "customer_42",
"url": "https://portal.example.com/claims",
"goal": "Declare the water damage claim and give me the claim number.",
"input": {
"data": {
"contract": "AX-4471",
"date": "2026-11-20"
},
"files": []
},
"pending": null,
"learn": true,
"used_recipe": null,
"template": null,
"created_by": {
"type": "key",
"id": "key_d160ed300d0cf627",
"hint": "hp_test_7eF…ZD9D",
"name": "default test key",
"owner_email": null
},
"recipe_chosen": null,
"recipe": null,
"dispute": null,
"result": {
"answer": "The claim is declared. Claim number SIN-2026-118.",
"data": {
"claim_number": "SIN-2026-118"
}
},
"files": [],
"usage": {
"steps": 14
},
"created_at": "2026-11-22T18:40:56.170Z",
"finished_at": "2026-11-22T18:40:56.190Z"
}Next steps
- Receive results without polling: Webhooks or Live updates.
- Act for your customers with their own sessions and accounts: Users and identity.
- Let your AI agent use Hapti: Build with AI agents.