Docs Sign in Get a key

Docs / Get started

Quickstart

Create a key, run your first Hapti task with cURL, JavaScript or Python, answer the agent when it asks, and read the result.

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.

Terminal
export HAPTI_KEY=hp_test_...

2. Install a library

cURL
# Nothing to install

3. 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
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."}'

With cURL, the answer is the task at the moment it was created. Ask for it again with its id until status is final:

Terminal
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.

JavaScript
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) },
);

A waiting task looks like this:

JSON
{
  "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.

JSON
{
  "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