# Hapti documentation > Hapti is an API that does tasks on websites that have no API. An agent operates a real browser by sight, like a person: it fills forms, books appointments, downloads invoices, submits claims, signs in with the person's stored accounts, asks when a value is missing, and returns the result with proof. You pay only when a task succeeds; test mode is free. --- Source: https://hapti.dev/docs/ # Introduction > Hapti is an API that does tasks on websites that have no API. An agent uses a real browser by sight and returns the result with proof. Hapti does the work that software cannot reach through an API. You send a website and a goal in plain words. An agent opens a real browser, looks at the screen, clicks and types like a person, and sends back the result with every step it took as proof. ```bash curl https://api.hapti.dev/v1/tasks \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://portal.example.com/claims", "goal": "Declare the water damage claim and give me the claim number.", "data": {"contract": "AX-4471", "date": "2026-11-20"}}' ``` ## When to use Hapti Use Hapti when a job has to be done on a website and that website has no API, or an API that does not cover the job. Typical tasks: - Book an appointment on a booking site, a town hall or a clinic. - Fill in and submit an online form, up to the confirmation page. - Download invoices, statements or certificates from a customer area. - Declare a claim, cancel a contract, update contact details. - Check the status of a file on a public administration portal. - Publish a listing or ask for a quote on a site without integration. When a proper API exists for the job, use that API: it will be faster and cheaper. Hapti is for everything else. ## How it works 1. **You create a task** with a starting address, a goal and the data the agent may use. 2. **An agent does it** in a real browser, by sight. It never invents a value: when one is missing, the task waits with a question that you or the person answer. 3. **You get the result** by webhook, by the live stream or by asking for the task: an answer, structured data if you asked for a schema, downloaded files, and the proof. 4. **You pay only if it succeeds.** A failed, blocked or cancelled task costs nothing, and test mode is always free. ## What makes it reliable for production - **People, not sessions.** Tasks for the same person share one device, one session, one memory, an email inbox and a vault of sign-in details the model never sees. See [Users and identity](/docs/users). - **Structured results.** Give a JSON Schema in `output` and the result follows it, or the task is not billed. See [Tasks](/docs/tasks). - **Built for integration.** Idempotency keys, versioned API, signed webhooks with retries, live streaming, cursor pagination and request logs. - **Built for agents.** A remote MCP server, an OpenAPI specification and plain Markdown docs. See [Build with AI agents](/docs/agents). ## Next steps - [Quickstart](/docs/quickstart): your first task in five minutes. - [Build with AI agents](/docs/agents): connect Claude Code, Cursor or any MCP client. - [Tasks API](/docs/api-tasks): every field and response. --- Source: https://hapti.dev/docs/quickstart # 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](https://app.hapti.dev) 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. ```bash export HAPTI_KEY=hp_test_... ``` ## 2. Install a library :::tabs ```bash cURL # Nothing to install ``` ```bash JavaScript npm install hapti-sdk ``` ```bash Python pip install hapti ``` ::: ## 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. :::tabs ```bash 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."}' ``` ```js JavaScript 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); ``` ```python Python 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: ```bash 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. :::tabs ```js 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) }, ); ``` ```python Python 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"]), ) ``` ```bash cURL 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: ```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 - Receive results without polling: [Webhooks](/docs/webhooks) or [Live updates](/docs/live). - Act for your customers with their own sessions and accounts: [Users and identity](/docs/users). - Let your AI agent use Hapti: [Build with AI agents](/docs/agents). --- Source: https://hapti.dev/docs/agents # Build with AI agents > Connect Hapti to Claude Code, Cursor, VS Code or any MCP client, and give coding agents the docs they need to integrate Hapti well. Hapti is made to be used by AI agents as much as by developers. An agent can call Hapti through its remote MCP server to do tasks on websites, and a coding agent can read these docs as plain text to integrate Hapti in your code. ## When an agent should use Hapti An agent should reach for Hapti when it has to act on a website that offers no API: fill a form, book a slot, download a document, check a status, sign in to a customer area. It should not use Hapti when the website has an API that covers the job, or for reading a public page that a simple fetch can read. ## Remote MCP server The MCP server lives at `https://api.hapti.dev/mcp` and speaks Streamable HTTP. It accepts two ways in: - **OAuth**, for apps such as Claude: you add the address, sign in to Hapti, choose the organisation and the mode, and approve. Nothing to copy. - **An API key** in the `Authorization` header, for code editors and scripts. Use a test key while you try it: test tasks are free. ### Claude (web and desktop) In Claude, open **Settings**, then **Connectors**, and add a custom connector with the address `https://api.hapti.dev/mcp`. Claude opens the Hapti sign-in: choose the organisation, **Test** or **Live**, and approve. The connection appears in the Hapti console under **Developers**, where you can disconnect it at any time. Any other client that supports MCP authorization works the same way: give it the address and it will open the Hapti sign-in. ### Install in one click The fastest way: create a test key in the [console](https://app.hapti.dev), under **Developers**. Next to the new key, the **Cursor**, **VS Code** and **Claude Code** buttons install Hapti with that key already filled in. From here, these links install Hapti with a placeholder: replace `hp_test_YOUR_KEY` with your key in the editor that opens. - [Add to Cursor](https://cursor.com/install-mcp?name=hapti&config=eyJ1cmwiOiJodHRwczovL2FwaS5oYXB0aS5kZXYvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIGhwX3Rlc3RfWU9VUl9LRVkifX0%3D) - [Install in VS Code](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522hapti%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.hapti.dev%252Fmcp%2522%252C%2522headers%2522%253A%257B%2522Authorization%2522%253A%2522Bearer%2520hp_test_YOUR_KEY%2522%257D%257D) ### Claude Code ```bash claude mcp add --transport http hapti https://api.hapti.dev/mcp \ --header "Authorization: Bearer hp_test_..." ``` ### Cursor Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project: ```json { "mcpServers": { "hapti": { "url": "https://api.hapti.dev/mcp", "headers": { "Authorization": "Bearer hp_test_..." } } } } ``` ### VS Code Add this to `.vscode/mcp.json`: ```json { "servers": { "hapti": { "type": "http", "url": "https://api.hapti.dev/mcp", "headers": { "Authorization": "Bearer hp_test_..." } } } } ``` ### Any other client Any MCP client that supports remote servers over HTTP with custom headers can connect with the same address and header. ## Tools | Tool | What it does | | --- | --- | | `start_task` | Give a goal to a Hapti agent that operates a real web browser by sight, like a person. | | `get_task` | State of a task. | | `answer_task` | Answer the question a waiting task asked. | | `approve_task` | Give or refuse the approval a waiting task asked for before a step that commits the person. | | `cancel_task` | Stop a task that is queued, running or waiting. | | `estimate_task` | The price of a task before starting it, from the earlier successes of the same task and its recipe: likely_cents, at_most_cents and what it is based on. | | `list_templates` | The ready-made tasks Hapti offers on sites that have no API (book an appointment, file a form, track an application, get invoices, cancel a subscription, place an order...), each with its id, what it does and its parameters. | | `list_tasks` | The latest tasks of this key, newest first, optionally only one status (for example running or waiting): find a task again when you lost its id. | | `list_recipes` | The recipes of this organisation, newest first: id, name, site, number of steps, uses. | | `get_balance` | The credit left for live tasks, in cents of US dollars. | The agent starts a task with `start_task`, then calls `get_task` with `wait_seconds` in a loop. When a task waits, the agent relays the question or the approval to the person and answers with `answer_task` or `approve_task`. It must never invent the answer. ## Docs for coding agents Every page of these docs exists as plain Markdown: add `.md` to its address, for example [/docs/quickstart.md](/docs/quickstart.md). Each page also has **Copy as Markdown**, **Ask Claude** and **Ask ChatGPT** buttons. | File | What it holds | | --- | --- | | [/llms.txt](/llms.txt) | A short map of Hapti and links to every page | | [/llms-full.txt](/llms-full.txt) | The whole documentation in one file | | [/openapi.json](/openapi.json) | The OpenAPI 3.1 specification of every endpoint | A prompt that works well with a coding agent: ```text Integrate Hapti in this project. Read https://hapti.dev/llms-full.txt first. Use the official SDK, send an Idempotency-Key with every task you create, receive results with a signed webhook endpoint, and verify the signature. Use the test key from HAPTI_KEY. Never invent data a task asks for: relay the question to the user. ``` ## Good practice for agents - Give the agent only the data the task needs, in `data`. It uses nothing else. - Set `user` to the person the task is for, so their session and stored accounts are used. - Ask for an `output` schema when a program reads the result. - Set `max_price_cents` when the agent runs without supervision. - Use test keys while building. Switch to a live key only for real tasks. --- Source: https://hapti.dev/docs/tasks # Tasks > How a Hapti task works from creation to result. Statuses, questions and approvals, structured output, budgets, languages, recipes and proof. A task is one job done by an agent on a website. You give a starting address, a goal and the data it may use. The agent works in a real browser until the goal is reached, it needs something from a person, or it cannot go on. ## Create a task :::tabs ```bash cURL curl https://api.hapti.dev/v1/tasks \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: claim-AX-4471" \ -d '{ "url": "https://portal.example.com/claims", "goal": "Declare the water damage claim and give me the claim number.", "data": {"contract": "AX-4471", "date": "2026-11-20"}, "user": "customer_42", "output": {"type": "object", "properties": {"claim_number": {"type": "string"}}, "required": ["claim_number"]} }' ``` ```js JavaScript const task = await hapti.tasks.create({ url: 'https://portal.example.com/claims', goal: 'Declare the water damage claim and give me the claim number.', data: { contract: 'AX-4471', date: '2026-11-20' }, user: 'customer_42', output: { type: 'object', properties: { claim_number: { type: 'string' } }, required: ['claim_number'] }, }); ``` ```python Python task = hapti.tasks.create({ "url": "https://portal.example.com/claims", "goal": "Declare the water damage claim and give me the claim number.", "data": {"contract": "AX-4471", "date": "2026-11-20"}, "user": "customer_42", "output": {"type": "object", "properties": {"claim_number": {"type": "string"}}, "required": ["claim_number"]}, }) ``` ::: The answer comes at once, before the agent starts: ```json { "id": "tsk_9a96d9052acef545", "object": "task", "batch": null, "schedule": null, "mode": "test", "status": "queued", "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": null, "files": [], "usage": null, "created_at": "2026-11-22T18:40:56.170Z", "finished_at": null } ``` Write the goal like you would brief a colleague: what to achieve, and what to report back. The goal can be in any language. The agent uses only what you put in `data` and never invents a missing value. ## Statuses | Status | Meaning | Final | Billed | | --- | --- | --- | --- | | `queued` | Waiting for a browser | No | No | | `running` | The agent is working | No | No | | `waiting` | The agent needs an answer or an approval, see `pending` | No | No | | `paused` | A live task waits for credit and starts by itself once credit is added | No | No | | `succeeded` | The goal is reached | Yes | Yes, in live mode | | `failed` | A technical failure on our side | Yes | No | | `blocked` | The site refused, or does not offer what the goal needs | Yes | No | | `needs_person` | Only the person can do the next step, for example in person or with a device they hold | Yes | No | | `incomplete` | The agent ran out of steps, budget or time before the end | Yes | No | | `cancelled` | You cancelled it | Yes | No | `finished_at` is set only once the task is final and its result is saved, so a task with a final status and a `finished_at` is safe to read. ## Questions and approvals When the agent needs something, the task goes to `waiting` and `pending` says what: - **A question** (`pending.type` is `question`): a value such as a code received by text message, or a choice between options. Answer with [`POST /v1/tasks/{id}/answer`](/docs/api-tasks#answer-a-question) and the `key` of the question. - **An approval** (`pending.type` is `approval`): only when you created the task with `"approval": "required"`. The agent stops before any step that commits the person, such as paying or sending. Answer with [`POST /v1/tasks/{id}/approve`](/docs/api-tasks#approve-or-refuse-a-step). `pending.action_url` is a page where the person answers by themselves, once, without an account or a key. It is the simplest way to reach a customer in your app, by email or by text message. By default the agent does not stop to ask permission: it does the final step that sends, confirms or pays. Use `"approval": "required"` when a person must confirm first, or give the person a [mandate](/docs/users#mandates) that says what the agent may do for them. ## Results | Field | What it holds | | --- | --- | | `result.answer` | What the agent reports, in plain words | | `result.data` | Structured data that follows your `output` schema | | `files` | Files the site gave, such as invoices or certificates, see [Files](/docs/files) | | `price_cents` | What was billed: 0 until a live task succeeds | | `usage` | The number of actions the agent took | ### Structured output Give a JSON Schema in `output` and `result.data` follows it. When the agent cannot fill the schema from what it saw, the task does not succeed and is not billed. Programs can trust `result.data` without parsing text. ### Languages The agent writes its answer and its questions in the language of the goal. Set `answer_language` to choose another one, such as `pt-BR` or `wo`. The browser takes the language and time zone of the person when you give a `user`, or of `locale` and `country`. Nothing is forced to English or to any default country. ## Budget and limits - `max_price_cents`: the agent stops before the price would go over it. - `max_steps`: the most actions the agent may take, from 1 to 500. A task that reaches its budget ends as `incomplete` and is not billed. ## Recipes A task that succeeds becomes a recipe: the path the agent took. The next time the same task runs for your organisation, the agent replays the recipe first, which is faster and costs fewer actions, and falls back to looking at the screen when the site has changed. Set `"learn": false` to neither learn nor replay, or `recipe` to replay a given one. See [GET /v1/recipes](/docs/api-recipes). ## Proof Every step of the agent and the screenshots it saw are kept for 90 days. Read them with [`GET /v1/tasks/{id}/proof`](/docs/api-tasks#get-the-proof), or delete them now with `DELETE`. If a billed task is wrong, [open a dispute](/docs/api-tasks#dispute-a-billed-task): the proof is checked and the price is refunded when the claim is right. ## Cancel and run again [`POST /v1/tasks/{id}/cancel`](/docs/api-tasks#cancel-a-task) stops a task that is not over. A cancelled task is never billed, even if the agent was about to finish. [`POST /v1/tasks/{id}/retry`](/docs/api-tasks#run-a-task-again) creates a new task with the same input. ## Follow a task Three ways, from the simplest to the most efficient: 1. **Ask for it** with [`GET /v1/tasks/{id}`](/docs/api-tasks#get-a-task). Fine for scripts. 2. **Stream it** with [`GET /v1/tasks/{id}/stream`](/docs/live): every step as it happens. 3. **Receive webhooks** on your server: see [Webhooks](/docs/webhooks). Best for production. --- Source: https://hapti.dev/docs/templates # Templates > Ready-made Hapti tasks for common jobs on websites without an API. Give a template id and its params instead of writing a goal. Templates are tasks that are already written and tuned. Instead of a `url` and a `goal`, you give a `template` and its `params`. Everything else works like any task: `user`, `data`, `output`, webhooks and the rest. ```json { "template": "recuperer_factures", "params": { "site": "https://billing.example.com", "period": "last 3 months" }, "user": "customer_42" } ``` ## Available templates | Template | What it does | Params | | --- | --- | --- | | `prendre_rdv` | On a booking site (prefecture, town hall, doctor...), books the first slot that fits. | `site`, `reason`, `window` | | `deposer_formulaire` | Fills in an official or online form with the person’s data and submits it through to the confirmation. | `site`, `purpose` | | `suivre_dossier` | Signs in and reports the status of a request: permit, benefit, application, claim... | `site`, `which` | | `telecharger_document` | Gets a certificate or document from a personal account and returns it as a file. | `site`, `document` | | `recuperer_factures` | Downloads the invoices of a customer account (energy, phone, suppliers) as files. | `site`, `period` | | `mettre_a_jour_infos` | Changes the address, phone, IBAN or other details in a customer account. | `site`, `change` | | `resilier` | Cancels a subscription or contract online through to the confirmation, declining retention offers. | `site`, `what`, `reason` | | `reclamer` | Files a claim: train delay, lost parcel, overpayment, faulty product. | `site`, `case` | | `publier_annonce` | Posts a listing on a classifieds site or marketplace, with photos and price. | `site`, `title`, `price`, `text` | | `demander_devis` | Fills in a supplier’s quote form, then waits for the answer in the person’s mailbox. | `site`, `need`, `wait_minutes` | | `passer_commande` | Orders on a supplier portal without an API, from the basket to the order number. | `site`, `items`, `delivery` | | `relever_portail` | Signs in to a portal and reads figures or statuses: sales, stock, orders. | `site`, `what`, `schema` | | `creer_compte` | Creates an account on a site with the person’s email and confirms the code received by email or SMS. | `site` | | `inscription_evenement` | Registers the person for an event, training or webinar, and reports the confirmation. | `site`, `choice` | List them with their params at any time with [`GET /v1/catalogue?lang=en`](/docs/api-catalogue). ```json { "object": "list", "data": [ { "id": "prendre_rdv", "group": "demarches", "name": "Book an appointment", "description": "On a booking site (prefecture, town hall, doctor…), books the first slot that fits.", "params": { "site": "address of the booking page", "reason": "reason for the appointment", "window": "preferred dates and times (optional)" } } ] } ``` ## When to write your own goal Templates cover frequent jobs. For anything else, a clear goal works just as well: say what to achieve and what to report back, and put the facts in `data`. --- Source: https://hapti.dev/docs/users # Users and identity > Act for each of your customers with their own device, session, memory, email inbox, phone number and vault of sign-in details. Most real tasks are done for someone: your customer, a patient, a tenant. Give each task the `user` it acts for, with your own id for that person. Hapti then keeps a stable identity for them from task to task, so sites see the same person coming back instead of a new robot each time. ```json { "url": "https://portal.example.com", "goal": "Download my last statement.", "user": "customer_42" } ``` You do not need to create the person first: the first task with a new `user` creates it. Create it explicitly to set their country, language and time zone in advance: ```json { "object": "user", "id": "customer_42", "name": "Ana Silva", "created_at": "2026-11-22T18:40:56.163Z", "mandate": null, "session": null, "device": { "locale": "pt-PT", "timezone": "Europe/Lisbon", "country": "pt", "country_set": true, "since": "2026-11-22T18:40:56.165Z" }, "limits": null, "accounts": [] } ``` ## What a person keeps | What | Default with a user | Turn it off | | --- | --- | --- | | **Device**: one browser profile, language, time zone and country | Always | | | **Session**: cookies and sign-ins saved at the end of a task and restored at the next | On | `"keep_session": false` | | **Memory**: lasting facts the agent learns about the person, never secrets | On | `"memory": false` | | **Email inbox**: an address the agent can give sites to receive codes and links, read by itself | On | `"mailbox": false` | | **Phone number**: receives the text messages sites send, when you gave the person one | On | `"phone": false` | | **Stored accounts**: sign-in details the agent types without the model seeing them | When listed in `accounts` | | ## Stored accounts Save the person's sign-in details for a site in the vault. They are sealed, and the agent types them into the browser without the model ever reading them. ```bash curl -X PUT https://api.hapti.dev/v1/users/customer_42/accounts/insurer \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"origin": "https://portal.example.com", "username": "ana.silva", "password": "...", "totp_secret": "JBSWY3DPEHPK3PXP"}' ``` Then name the account in a task: ```json { "url": "https://portal.example.com", "goal": "Download my last statement.", "user": "customer_42", "accounts": ["insurer"] } ``` With `totp_secret`, the agent also fills the two-factor code. Secrets are never returned by the API and never written to logs. ### Connect links You may prefer never to hold the person's passwords at all. Create a connect link: a page, with your brand, where the person types their own details. You never see them. ```bash curl https://api.hapti.dev/v1/users/customer_42/connect \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"accounts": [{"account": "insurer", "origin": "https://portal.example.com"}]}' ``` The answer holds a `url` to send to the person, and an `expires_at`. You receive a `user.account_connected` event once they are done. ## Mandates A mandate records what the agent may do for the person, and how they agreed to it. It is kept with the person and with the proof of each task. ```bash curl https://api.hapti.dev/v1/users/customer_42/mandate \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"scope": "Declare insurance claims and download invoices", "given_by": "Ana Silva, in the app on 2026-11-20"}' ``` Add `sites` to limit it to some addresses and `until` to make it end. When a task must wait for a human decision before committing the person, create it with `"approval": "required"`. ## Limits per person Protect yourself from a runaway loop or an abusive end user with limits per person: ```bash curl -X PATCH https://api.hapti.dev/v1/users/customer_42 \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"limits": {"tasks_per_day": 20, "cents_per_month": 500}}' ``` A task over a limit is refused with a clear error. Send `"limits": null` to remove them. ## Email and phone - [`POST /v1/users/{user}/inbox`](/docs/api-users#open-an-email-inbox) opens a lasting address for the person, and [`GET /v1/users/{user}/emails`](/docs/api-users#list-received-emails) lists what it received. - [`POST /v1/users/{user}/phone`](/docs/api-users#give-a-phone-number) gives the person a real number that receives texts. It needs a live key and is paid each month from your credit. ## Forget a person [`DELETE /v1/users/{user}`](/docs/api-users#forget-a-person) erases the session, memory, stored accounts, mandate, inbox and received messages of the person. Use it when your customer closes their account or asks to be forgotten. --- Source: https://hapti.dev/docs/live # Live updates > Follow a Hapti task step by step as it happens with Server-Sent Events, or every task of your organisation at once. Hapti streams what happens with [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events). It is the fastest way to show progress in your app, and the libraries use it to return as soon as a task ends. ## Follow one task :::tabs ```js JavaScript for await (const e of hapti.tasks.stream('tsk_...')) { if (e.event === 'step') console.log(e.data.summary); if (e.event === 'task') console.log('status', e.data.status); } ``` ```python Python for e in hapti.tasks.stream("tsk_..."): if e["event"] == "step": print(e["data"].get("summary")) if e["event"] == "task": print("status", e["data"]["status"]) ``` ```bash cURL curl -N https://api.hapti.dev/v1/tasks/tsk_.../stream \ -H "Authorization: Bearer $HAPTI_KEY" ``` ::: | Event | Data | When | | --- | --- | --- | | `task` | The full task | First, then each time its status, question, result or price changes | | `step` | One action of the agent, with a `summary` | Each time the agent acts | | `screenshot` | `n` and the `url` of the image | Each time a screenshot is saved | | `done` | `id` and final `status` | Once, at the end. The stream then closes | | `reconnect` | `reason` | After 30 minutes: connect again | Each `step` carries an `id`. If the connection drops, connect again with the header `Last-Event-ID` set to the last id you received, and the stream resumes right after it, without gaps or repeats. The libraries do this for you. A comment line `: ping` is sent every 15 seconds so proxies keep the connection open. ## Wait for the end with the libraries `tasks.wait` and `tasks.run` follow the stream and return the moment the task is over. They fall back to asking for the task at intervals when a stream cannot be opened. ```js const task = await hapti.tasks.run( { url: 'https://portal.example.com', goal: 'Download my last statement.' }, { onStep: (s) => progress(s.summary) }, ); ``` ## Follow every task `GET /v1/stream` sends a `task` event each time any task of the key mode changes state. Use it to keep a dashboard up to date. ```bash curl -N https://api.hapti.dev/v1/stream -H "Authorization: Bearer $HAPTI_KEY" ``` > **Tip** For a server that must not miss anything, even while it is down, use [webhooks](/docs/webhooks) and the [events API](/docs/events). Streams are for live display. --- Source: https://hapti.dev/docs/webhooks # Webhooks > Receive Hapti events on your server, signed and retried for three days. Endpoints, event types, signature checks, retries, secret rotation and recovery. Webhooks push each event to your server the moment it happens: a task succeeds, waits for an answer, fails. They are the right way to get results in production. ## Create an endpoint An endpoint is an https address on your server, the events it wants, and its own signing secret. You can have up to 16 per mode. ```bash curl https://api.hapti.dev/v1/webhooks/endpoints \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://api.example.com/hooks/hapti", "events": ["task.succeeded", "task.failed", "task.waiting"], "description": "Production"}' ``` ```json { "id": "we_0e47caf33717b1a8", "object": "webhook_endpoint", "url": "https://api.example.com/hooks/hapti", "events": [ "task.succeeded", "task.failed", "task.waiting" ], "description": "Production", "enabled": true, "disabled_reason": null, "disabled_at": null, "failing_since": null, "last_success_at": null, "headers": {}, "mode": "test", "secret": "whsec_0f9c3a…", "previous_secret_expires_at": null, "created_at": "2026-11-22T18:40:56.225Z" } ``` Keep the `secret`: it is shown here in full. You can reveal it later with `GET /v1/webhooks/endpoints/{id}/secret`. Endpoints can also be managed in the console, under **Developers, Webhooks**, where **Send a test** delivers a signed `ping` event at once and shows the answer of your server. `events` takes event types, a family such as `user.*`, or `["*"]` for every event, including the ones added later. ## Event types | Event | When | | --- | --- | | `task.created` | A task was created. | | `task.paused` | A live task waits for credit. | | `task.waiting` | The agent asks a question or an approval. | | `task.succeeded` | A task succeeded. | | `task.failed` | A task failed. | | `task.cancelled` | A task was cancelled. | | `batch.finished` | Every task of a batch is over. | | `email.received` | An email reached a person's inbox. | | `sms.received` | A text reached a person's number. | | `user.account_connected` | A person connected an account. | | `user.account_removed` | A person removed an account. | | `user.forward_started` | A person started forwarding mail. | | `user.forward_stopped` | A person stopped forwarding mail. | | `user.memory_forgotten` | A person erased what the agent kept. | | `ping` | A test sent from the console or the API. | ## The payload Every delivery is a POST with a JSON event. The same event, with the same `id`, goes to every endpoint that wants it. ```json { "id": "evt_c3b9a22cc8666f754e930055", "object": "event", "type": "task.succeeded", "api_version": "2026-11-22", "created_at": "2026-11-22T18:40:56.191Z", "mode": "test", "data": { "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" } } ``` | Header | Value | | --- | --- | | `Hapti-Signature` | `t=` the time, then one `v1=` signature per valid secret | | `Hapti-Event` | The event type | | `Hapti-Event-Id` | The event id. Use it to ignore an event you already handled | | `Hapti-Delivery` | The delivery id, as shown in the console and the API | | `Hapti-Attempt` | 1 for the first try, then 2, 3 and so on | ## Verify the signature Always check that a delivery comes from Hapti before you trust it. The signature is an HMAC SHA-256 of the time, a dot and the raw body, with your endpoint secret. Use the raw body exactly as received, before any JSON parsing. :::tabs ```js JavaScript import express from 'express'; import Hapti from 'hapti-sdk'; const app = express(); app.post('/hooks/hapti', express.raw({ type: 'application/json' }), async (req, res) => { const ok = await Hapti.verifyWebhook(req.body, req.get('Hapti-Signature'), process.env.HAPTI_WEBHOOK_SECRET); if (!ok) return res.status(400).end(); const event = JSON.parse(req.body); res.status(200).end(); await handle(event); }); ``` ```python Python import os from flask import Flask, request from hapti import verify_webhook app = Flask(__name__) @app.post("/hooks/hapti") def hapti_hook(): raw = request.get_data() if not verify_webhook(raw, request.headers.get("Hapti-Signature"), os.environ["HAPTI_WEBHOOK_SECRET"]): return "", 400 handle(request.get_json()) return "", 200 ``` ```js Node without the SDK import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(raw, header, secret, tolerance = 300) { const parts = header.split(',').map((p) => p.split('=')); const t = Number(parts.find(([k]) => k === 't')?.[1]); if (!t || Math.abs(Date.now() / 1000 - t) > tolerance) return false; const mac = createHmac('sha256', secret).update(`${t}.${raw}`).digest('hex'); return parts.filter(([k]) => k === 'v1').some(([, v]) => v.length === mac.length && timingSafeEqual(Buffer.from(v), Buffer.from(mac))); } ``` ::: The libraries refuse a signature older than 5 minutes, which stops replays. While a secret is being rotated, a delivery carries two `v1` signatures: accept the delivery when any of them matches. ## Retries Answer with any 2xx status within 15 seconds. Anything else is retried, up to 9 attempts over about three days: at once, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours and 24 hours, with a little random spread. Every attempt is kept with its status, time and answer, in the console and in [`GET /v1/webhooks/deliveries/{id}`](/docs/api-webhooks#get-a-delivery). - Deliveries to one endpoint keep their order. A slow or failing endpoint never delays the others. - When your server answers 5xx, 429 or nothing, its endpoint rests 30 seconds before the next try. - An event can arrive more than once, for example when your server timed out after handling it. Use `Hapti-Event-Id` to handle each event once. - Answer fast and do the work afterwards, in a queue if it is long. ## When an endpoint keeps failing An endpoint that has failed for three days without a single success is paused, its waiting deliveries are closed, and the owners and admins of your organisation get an email. Once your server works again: 1. Enable the endpoint again: `PATCH /v1/webhooks/endpoints/{id}` with `{"enabled": true}`. 2. Send what it missed: `POST /v1/webhooks/endpoints/{id}/recover`. Every event of the last three days that never reached it is sent once. Give `since` to go back up to 30 days. ## Rotate a secret `POST /v1/webhooks/endpoints/{id}/roll-secret` creates a new secret. The old one stays valid for 24 hours, and every delivery carries both signatures meanwhile, so you can deploy the new secret without losing an event. Send `{"expires_in_hours": 0}` to drop the old one at once, after a leak for example. ## Custom headers An endpoint can send up to 10 headers of your own with each delivery, for example to pass a gateway that wants an `Authorization` header. They are stored sealed and shown masked. ```json { "url": "https://gateway.example.com/hapti", "headers": { "Authorization": "Bearer gw_...", "X-Tenant": "acme" } } ``` ## A webhook for one task A task or a batch can also take a `webhook` address that receives the events of that task only. These deliveries are signed with your organisation secret, which you read with `GET /v1/webhook/secret` or in the console. Endpoints are the better choice for most apps: one place, chosen events, their own secrets. ## Security Endpoints must be public https addresses. Addresses on private networks, localhost and cloud metadata services are refused when you create the endpoint and again at the moment of sending, after the name is resolved. --- Source: https://hapti.dev/docs/events # Events > Read every Hapti event of the last 30 days through the API, the same events webhooks send. Use it to catch up, reconcile or poll. Every event Hapti sends by webhook is also stored for 30 days, and can be read through the API even if you have no webhook at all. Use it to catch up after downtime, to reconcile, or when your server cannot receive webhooks. ```bash curl "https://api.hapti.dev/v1/events?type=task.succeeded&since=2026-11-20" \ -H "Authorization: Bearer $HAPTI_KEY" ``` ```json { "object": "list", "data": [ { "id": "evt_c3b9a22cc8666f754e930055", "object": "event", "type": "task.succeeded", "api_version": "2026-11-22", "created_at": "2026-11-22T18:40:56.191Z", "mode": "test", "data": { "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" } } ], "has_more": false, "next_cursor": null, "total": 1 } ``` | Parameter | What it does | | --- | --- | | `type` | One event type, or a family such as `task.*` | | `object` | Only the events of this task or object id | | `since` | Only the events from this date | | `limit`, `cursor` | Paging, see [Pagination](/docs/pagination) | An event is the same object as a webhook payload, with the same `id`, so you can mix both and handle each event once. ## Polling with events When you cannot receive webhooks, poll `GET /v1/events` with the `created_at` of the last event you handled as `since`, every few seconds. Events come newest first, and each one has a stable `id`. ## Event types | Event | When | | --- | --- | | `task.created` | A task was created. | | `task.paused` | A live task waits for credit. | | `task.waiting` | The agent asks a question or an approval. | | `task.succeeded` | A task succeeded. | | `task.failed` | A task failed. | | `task.cancelled` | A task was cancelled. | | `batch.finished` | Every task of a batch is over. | | `email.received` | An email reached a person's inbox. | | `sms.received` | A text reached a person's number. | | `user.account_connected` | A person connected an account. | | `user.account_removed` | A person removed an account. | | `user.forward_started` | A person started forwarding mail. | | `user.forward_stopped` | A person stopped forwarding mail. | | `user.memory_forgotten` | A person erased what the agent kept. | | `ping` | A test sent from the console or the API. | --- Source: https://hapti.dev/docs/batches # Batches and schedules > Run many Hapti tasks at once with a batch, or the same task again and again on a schedule, in the time zone of your choice. ## Batches A batch runs many tasks at once and tracks them together. Give a list of `tasks`, or one `template` and a list of `items` that each change what differs. ```bash curl https://api.hapti.dev/v1/batches \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoices-2026-11" \ -d '{ "name": "November invoices", "template": {"url": "https://billing.example.com", "goal": "Download the invoice of November and give its total."}, "items": [{"user": "customer_42"}, {"user": "customer_43"}] }' ``` ```json { "id": "bat_344f0b5bbdb6853e", "object": "batch", "mode": "test", "name": "November invoices", "total": 2, "done": 0, "counts": { "queued": 2, "paused": 0, "running": 0, "waiting": 0, "succeeded": 0, "failed": 0, "blocked": 0, "incomplete": 0, "needs_person": 0, "cancelled": 0 }, "billed_cents": 0, "created_at": "2026-11-22T18:40:56.210Z", "finished_at": null, "cancelled": false } ``` - `GET /v1/batches/{id}` gives the counts per status and what was billed. - `GET /v1/batches/{id}/tasks` lists its tasks, with `status` to filter. - `POST /v1/batches/{id}/cancel` cancels every task that is not over. - A `batch.finished` event is sent when every task of the batch is over. ## Schedules A schedule creates the same task on a cron expression or every interval, in a time zone. ```bash curl https://api.hapti.dev/v1/schedules \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Monday report", "cron": "0 8 * * 1", "timezone": "Europe/Lisbon", "task": {"url": "https://portal.example.com/reports", "goal": "Download the weekly report."} }' ``` ```json { "id": "sch_f23abc98afc7afcc", "object": "schedule", "mode": "test", "name": "Monday report", "every": null, "cron": "0 8 * * 1", "timezone": "Europe/Lisbon", "paused": false, "next_run_at": "2026-11-23T08:00:00.000Z", "until": null, "runs": 0, "last_task": null, "last_run_at": null, "last_error": null, "task": { "url": "https://portal.example.com/reports", "goal": "Download the weekly report." }, "created_at": "2026-11-22T18:40:56.222Z" } ``` Pause or resume it with `PATCH /v1/schedules/{id}` and `{"paused": true}` or `false`. Each task it creates carries the `schedule` id, so you can follow them like any other task. --- Source: https://hapti.dev/docs/files # Files > Give Hapti tasks the files to upload on a site, and download the documents a site gave during a task, such as invoices and certificates. ## Files the agent uploads Give `files` when the site asks for documents, such as an identity card or a proof of address. Each file has a `name` and either its content in `base64`, or an https `url` where Hapti fetches it. ```json { "url": "https://portal.example.com/apply", "goal": "Submit the application with the documents.", "files": [ { "name": "passport.pdf", "url": "https://files.example.com/signed/abc" }, { "name": "proof-of-address.jpg", "base64": "/9j/4AAQSkZJRg..." } ] } ``` Up to 20 files, 50 MB each and 100 MB in all. Two files cannot share a name. ## Files the site gives When the site gives a document during the task, the agent keeps it. A finished task lists them in `files`, each with a `url` you download with your key: ```bash curl -OJ https://api.hapti.dev/v1/tasks/tsk_.../files/invoice-2026-11.pdf \ -H "Authorization: Bearer $HAPTI_KEY" ``` Files are kept with the proof of the task, and only your organisation can download them. --- Source: https://hapti.dev/docs/authentication # Authentication > Authenticate to the Hapti API with a bearer key. Test keys are free; live keys run real tasks and are billed only when a task succeeds. Every request carries an API key in the `Authorization` header: ```bash curl https://api.hapti.dev/v1/me -H "Authorization: Bearer hp_test_..." ``` Create and revoke keys in the [console](https://app.hapti.dev), under **Developers**. A key belongs to your organisation and to one mode. ## Test and live | | Test keys `hp_test_` | Live keys `hp_live_` | | --- | --- | --- | | Price | Always free | Billed only when a task succeeds | | What the agent does | Works on the real site, but holds back any request that would send the data you gave, so nothing is submitted for real | Does the task for real | | Data | Tasks, people and webhooks of the test mode only | Tasks, people and webhooks of the live mode only | Build and test with a test key, then switch the key. Your code does not change. ## OAuth for AI apps AI apps such as Claude connect to the [MCP server](/docs/agents) with OAuth instead of a key: the person signs in to Hapti, chooses the organisation and the mode, and approves. The app then holds an access token that lasts one hour and renews itself, tied to that person. It stops working as soon as the connection is removed in **Developers**, or the person leaves the organisation. Hapti follows the MCP authorization specification: protected resource metadata at `/.well-known/oauth-protected-resource`, dynamic client registration, client metadata documents and PKCE. ## Keep keys secret - Keep keys on your server, never in a browser, a mobile app or a public repository. - Give each service its own key, so you can revoke one without stopping the others. - Revoke a key at once if it leaks. Requests made with it are listed in **Developers, Requests**, with the address they came from. A missing or wrong key gets a `401`: ```json { "error": { "type": "authentication_error", "code": 401, "message": "a valid key is required: Authorization: Bearer hp_live_… or hp_test_…" } } ``` --- Source: https://hapti.dev/docs/errors # Errors > How the Hapti API reports errors. HTTP status codes, error types, stable reason codes and what to do about each of them. Errors come with an HTTP status and a JSON body that says what went wrong in plain words. ```json { "error": { "type": "invalid_request_error", "code": 400, "message": "url: an http or https address is required" } } ``` | Field | What it holds | | --- | --- | | `error.type` | The family of the error, from the status | | `error.code` | The HTTP status | | `error.message` | What went wrong and how to fix it, for a developer | | `error.reason` | A stable code for some errors, to test in your code | ## Status codes | Status | Type | Meaning | Retry | | --- | --- | --- | --- | | `400` | `invalid_request_error` | A field is missing or wrong: read the message | No, fix the request | | `401` | `authentication_error` | The key is missing, wrong or revoked | No | | `402` | `billing_error` | Not enough credit, and the task was set to refuse rather than wait | After adding credit | | `403` | `permission_error` | The key or the person may not do this | No | | `404` | `not_found_error` | No such object in this organisation and mode | No | | `409` | `conflict_error` | The object is not in a state that allows it, or an idempotency key is in use | Depends on the reason | | `429` | `rate_limit_error` | Too many requests: wait for the `Retry-After` header | Yes, after the wait | | `500` | `api_error` | An error on our side | Yes, with an idempotency key | | `502` | `engine_error` | The browser could not be reached | Yes, with an idempotency key | | `503` | `unavailable_error` | A service is not available for a moment | Yes | ## Reason codes | Reason | Status | What to do | | --- | --- | --- | | `insufficient_credit` | 402 | Add credit, or let tasks wait with `on_insufficient_credit: "pause"` | | `user_limit_reached` | 429 | The person reached a limit you set: see [limits per person](/docs/users#limits-per-person) | | `idempotency_conflict` | 409 | The same idempotency key was used with another request: use a new key | | `idempotency_in_progress` | 409 | A request with this key is still running: retry in a moment | | `idempotency_key_invalid` | 400 | Use 1 to 255 visible characters, without spaces | | `version_unknown` | 400 | `Hapti-Version` is not a known version: see [Versioning](/docs/versioning) | | `live_only` | 402 | This needs a live key, for example a phone number | | `already_disputed` | 409 | This task already has a dispute | ## Request ids Every answer carries a `Request-Id` header. Give it to support, or find the request with its body in **Developers, Requests** in the console. ## Retrying safely Retry `429` and `5xx` answers with a growing wait. Send an [idempotency key](/docs/idempotency) with every POST, so that a retry never does the work twice. The official libraries do both for you. --- Source: https://hapti.dev/docs/idempotency # Idempotency > Retry any Hapti POST request safely with an Idempotency-Key, so a dropped connection never creates a task or a charge twice. A network can drop an answer after the server has acted. If you then retry a `POST /v1/tasks`, you could start the same task twice and pay twice. An idempotency key prevents it. ```bash curl https://api.hapti.dev/v1/tasks \ -H "Authorization: Bearer $HAPTI_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-4512" \ -d '{"url": "https://shop.example.com", "goal": "Order item 4512"}' ``` ## How it works - **Same key, same request**, within 24 hours: you get the first answer again, status and body, and nothing is done twice. The answer carries `Idempotent-Replayed: true`. - **Same key, another request**: refused with `409` and the reason `idempotency_conflict`. - **Same key while the first request still runs**: refused with `409` and the reason `idempotency_in_progress`. Retry in a moment. - **A request that failed** with an error frees its key, so you can fix it and retry with the same key. Keys work on every `POST` under `/v1`: tasks, batches, schedules, retries, webhook endpoints. They are kept apart per organisation and per mode. ## Choosing a key Use something unique to the work, from your own system: an order id, a claim id, or a random UUID you store with the job before calling Hapti. A key has 1 to 255 visible characters, without spaces. The official libraries add a random key to every POST by themselves, so their automatic retries are always safe. Pass your own key to also be safe across restarts of your program. :::tabs ```js JavaScript await hapti.tasks.create(task, { idempotencyKey: `claim-${claim.id}` }); ``` ```python Python hapti.tasks.create(task, idempotency_key=f"claim-{claim['id']}") ``` ::: --- Source: https://hapti.dev/docs/versioning # Versioning > Hapti API versions are dated. Your organisation is pinned to one, so a change never breaks your app until you choose to upgrade. Hapti versions its API with dates. When a change could break an existing app, it comes with a new version. Your organisation is pinned to the version of the day it was created, and keeps its behaviour until you choose to move. Every answer says which version it used: ```http Hapti-Version: 2026-11-22 ``` ## Try another version Send the header on a request to use another version for that request only. This is how you test an upgrade before you switch. ```bash curl https://api.hapti.dev/v1/tasks -H "Authorization: Bearer $HAPTI_KEY" -H "Hapti-Version: 2026-11-22" ``` An unknown version is refused with `400` and the reason `version_unknown`. ## Upgrade Change the version of your organisation in the console, under **Developers, Configuration**. [`GET /v1/versions`](/docs/api-account#api-versions) lists every version, what it changed, and the one you are pinned to. Webhook events carry the `api_version` they were made with. ## Versions | Version | Changes | | --- | --- | | `2026-11-22` | A live task without enough credit is created paused and starts by itself once credit is added (on_insufficient_credit: refuse keeps the 402). Lists are paged with has_more, next_cursor and total. price_cents is what was billed, 0 until a live task succeeds; starting_price_cents gives the starting price. | | `2026-11-01` | A live task without enough credit is refused with 402 insufficient_credit. | Adding a field to an answer, a new endpoint or a new event type is not a breaking change: your code should ignore fields it does not know. --- Source: https://hapti.dev/docs/pagination # Pagination > Hapti lists are paged with a cursor. Read has_more and next_cursor to get every item, even while new ones arrive. Lists come newest first, one page at a time. ```json { "object": "list", "data": [ { "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" } ], "has_more": false, "next_cursor": null, "total": 1 } ``` | Field | What it holds | | --- | --- | | `data` | The items of this page | | `has_more` | `true` when there is another page | | `next_cursor` | What to send as `cursor` to get the next page | | `total` | How many items match, in all | Send `limit`, from 1 to 100, to choose the size of a page. A cursor stays valid while new items arrive: you never see an item twice or miss one. :::tabs ```js JavaScript for await (const task of hapti.tasks.all({ status: ['succeeded'] })) { console.log(task.id); } ``` ```python Python for task in hapti.tasks.all(status=["succeeded"]): print(task["id"]) ``` ```bash cURL curl "https://api.hapti.dev/v1/tasks?limit=100&cursor=eyJ..." -H "Authorization: Bearer $HAPTI_KEY" ``` ::: --- Source: https://hapti.dev/docs/limits # Rate limits > How many requests and new tasks the Hapti API accepts per minute, and how to handle a 429 answer with its Retry-After header. Each organisation and mode has its own limits: | What | Limit | | --- | --- | | Requests | 600 per minute | | New tasks | 60 per minute | Over a limit, the answer is `429` with a `Retry-After` header that says how many seconds to wait. The official libraries wait and retry by themselves. To start many tasks at once, use a [batch](/docs/batches): one request creates them all. If you need higher limits, write to contact@hapti.dev. You can also set limits for each person you act for, so one end user cannot use more than you allow: see [limits per person](/docs/users#limits-per-person). --- Source: https://hapti.dev/docs/pricing # Pricing and billing > Hapti bills only tasks that succeed, per 10 actions of the agent, from a prepaid credit. Test mode is free. How credit, pauses and refunds work. ## You pay for success A live task is billed only when it succeeds. Failed, blocked, incomplete and cancelled tasks cost nothing, and test mode is always free. | | Price | | --- | --- | | A successful live task | $0.10 per 10 actions of the agent | | Time spent waiting for an answer | Free | | Residential proxy, when you ask for it | $2.90 per GB, only when the task succeeds | A task of 1 to 10 actions costs $0.10, 11 to 20 actions twice that, and so on. The price is in `price_cents` once the task succeeds. Use [`POST /v1/tasks/estimate`](/docs/api-tasks#estimate-a-task) to know the likely price first, and `max_price_cents` to set a ceiling. ## Credit Live tasks are paid from a prepaid credit, in the console under **Billing**. Add a card to receive a first credit offered once, top up any amount, or turn on automatic top-up with a monthly cap. When the credit is not enough for a new live task, the task is created `paused` and starts by itself as soon as credit is added. A paused task that never gets credit stops after 7 days, unbilled. Set `"on_insufficient_credit": "refuse"` to get a `402` instead. ## Disputes If a billed task did not do what it should have, [open a dispute](/docs/api-tasks#dispute-a-billed-task). The proof of the task is checked and the price is refunded to your credit when the claim is right. ## Usage [`GET /v1/usage`](/docs/api-account#usage-by-day) gives what was billed per day, and `GET /v1/usage/users` per person you act for. --- Source: https://hapti.dev/docs/sdks # Libraries > The official Hapti libraries for JavaScript and Python. Retries, idempotency, live waiting, pagination and webhook signature checks built in. The libraries wrap the API with the good habits built in: an idempotency key on every POST, retries of `429` and `5xx` with a growing wait, live waiting through the stream, pagination and webhook checks. ## JavaScript and TypeScript ```bash npm install hapti-sdk ``` ```js import Hapti from 'hapti-sdk'; const hapti = new Hapti(process.env.HAPTI_KEY); const task = await hapti.tasks.run( { url: 'https://portal.example.com', goal: 'Download my last statement.', user: 'customer_42' }, { onWaiting: (pending) => askTheCustomer(pending.text), onStep: (s) => console.log(s.summary) }, ); ``` It works in Node 18 and later, has no dependencies, and ships its TypeScript types. ## Python ```bash pip install hapti ``` ```python from hapti import Hapti hapti = Hapti() task = hapti.tasks.run( {"url": "https://portal.example.com", "goal": "Download my last statement.", "user": "customer_42"}, on_waiting=lambda pending, task: ask_the_customer(pending["text"]), ) ``` It has no dependencies and works with Python 3.9 and later. ## Options | Option | JavaScript | Python | Default | | --- | --- | --- | --- | | API key | first argument | first argument | `HAPTI_API_KEY` | | Base address | `baseUrl` | `base_url` | `https://api.hapti.dev` | | Retries | `retries` | `retries` | 3 | | API version | `version` | `version` | your pinned version | ## What they cover | Area | JavaScript | Python | | --- | --- | --- | | Tasks | `tasks.create`, `get`, `list`, `all`, `run`, `wait`, `stream`, `answer`, `approve`, `cancel`, `retry`, `estimate`, `proof`, `file` | `tasks.create`, `get`, `list`, `all`, `run`, `wait`, `stream`, `answer`, `approve`, `cancel`, `retry`, `estimate`, `proof`, `file` | | People | `users.create`, `get`, `update`, `forget`, `putAccount`, `connectLink`, `giveMandate`, `setLimits`, `phone` | `users.create`, `get`, `update`, `forget`, `put_account`, `connect_link`, `give_mandate`, `set_limits`, `phone` | | Webhooks | `webhooks.endpoints.*`, `webhooks.deliveries`, `Hapti.verifyWebhook` | `webhooks.endpoints.*`, `webhooks.deliveries`, `verify_webhook` | | Events | `eventLog.list`, `eventLog.all`, `events` (live) | `webhooks.list_events`, `events` (live) | | Batches and schedules | `batches.*`, `schedules.*` | `batches.*`, `schedules.*` | --- Source: https://hapti.dev/docs/api-tasks # Tasks API > Reference of the Hapti tasks endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Create a task ```http POST /v1/tasks ``` Starts an agent that does the goal on the website, by sight, in a real browser. Returns at once; follow the task with GET, the live stream or webhooks. | Parameter | In | Description | | --- | --- | --- | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | | Field | Type | Description | | --- | --- | --- | | `url` | string | The page to start on. | | `goal` | string | What to achieve and what to report back, in plain words, in any language. | | `data` | object | The facts the agent may use. It never invents a missing value: it asks. | | `template` | string | A catalogue template id, instead of url and goal. | | `params` | object | The params of the template. | | `user` | string | The person the task acts for. Gives the task their device, session, memory, inbox and stored accounts. | | `accounts` | array | Stored accounts of the person the agent may sign in with. | | `output` | object | A JSON Schema for result.data. A task whose answer cannot follow it is not billed. | | `files` | array | Files the agent may upload on the site: up to 20, 50 MB each, 100 MB in all. | | `webhook` | string | An https address that receives the events of this task only. | | `approval` | string: `mandate`, `required` | required: the agent waits for your approval before any step that commits the person. | | `max_price_cents` | integer | The agent stops before the price would go over it. | | `max_steps` | integer | | | `answer_language` | string | Language of the answer and questions, like fr, pt-BR or wo. By default, the language of the goal. | | `locale` | string | Language of the browser, like pt-PT. | | `country` | string | Two letters: the country the sites see the person in. | | `proxy` | boolean | Go out through a residential address in that country, billed per GB when the task succeeds. | | `memory` | boolean | true by default with a user. | | `keep_session` | boolean | true by default with a user. | | `learn` | boolean | true by default: a success becomes a recipe. | | `recipe` | string | A recipe id to replay. | | `on_insufficient_credit` | string: `pause`, `refuse` | pause by default: a live task without enough credit waits and starts once credit is added. | ```json Request { "url": "https://portal.example.com/claims", "goal": "Declare the water damage claim and give me the claim number.", "data": { "contract": "AX-4471", "date": "2026-11-20" }, "user": "customer_42" } ``` ```json Response 201 { "id": "tsk_9a96d9052acef545", "object": "task", "batch": null, "schedule": null, "mode": "test", "status": "queued", "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": null, "files": [], "usage": null, "created_at": "2026-11-22T18:40:56.170Z", "finished_at": null } ``` ## List tasks ```http GET /v1/tasks ``` Tasks of the key mode, newest first, paged with a cursor. | Parameter | In | Description | | --- | --- | --- | | `limit` | query | 1 to 100, 25 by default | | `cursor` | query | next_cursor of the previous page | | `status` | query | One status or several separated by commas | | `user` | query | Only the tasks of this person | | `q` | query | Search the goal, the site, the person or the id | | `since` | query | ISO date | | `until` | query | ISO date | | `template` | query | Catalogue template id | | `batch` | query | Batch id | ```json Response 200 { "object": "list", "data": [ { "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" } ], "has_more": false, "next_cursor": null, "total": 1 } ``` ## Estimate a task ```http POST /v1/tasks/estimate ``` Gives the likely price of a task before you create it, from your earlier successes of the same task and its recipe. | Field | Type | Description | | --- | --- | --- | | `url` | string | The page to start on. | | `goal` | string | What to achieve and what to report back, in plain words, in any language. | | `data` | object | The facts the agent may use. It never invents a missing value: it asks. | | `template` | string | A catalogue template id, instead of url and goal. | | `params` | object | The params of the template. | | `user` | string | The person the task acts for. Gives the task their device, session, memory, inbox and stored accounts. | | `accounts` | array | Stored accounts of the person the agent may sign in with. | | `output` | object | A JSON Schema for result.data. A task whose answer cannot follow it is not billed. | | `files` | array | Files the agent may upload on the site: up to 20, 50 MB each, 100 MB in all. | | `webhook` | string | An https address that receives the events of this task only. | | `approval` | string: `mandate`, `required` | required: the agent waits for your approval before any step that commits the person. | | `max_price_cents` | integer | The agent stops before the price would go over it. | | `max_steps` | integer | | | `answer_language` | string | Language of the answer and questions, like fr, pt-BR or wo. By default, the language of the goal. | | `locale` | string | Language of the browser, like pt-PT. | | `country` | string | Two letters: the country the sites see the person in. | | `proxy` | boolean | Go out through a residential address in that country, billed per GB when the task succeeds. | | `memory` | boolean | true by default with a user. | | `keep_session` | boolean | true by default with a user. | | `learn` | boolean | true by default: a success becomes a recipe. | | `recipe` | string | A recipe id to replay. | | `on_insufficient_credit` | string: `pause`, `refuse` | pause by default: a live task without enough credit waits and starts once credit is added. | ```json Response 200 { "object": "estimate", "level": "standard", "currency": "usd", "recipe": null, "based_on": "nothing yet: this task has never succeeded here", "typical_actions": null, "likely_cents": 10, "at_most_cents": null, "minimum_cents": 10, "charged": "never: test mode is free" } ``` ## Get a task ```http GET /v1/tasks/{id} ``` The current state of a task, with its result once it is over. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | ```json Response 200 { "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" } ``` ## Answer a question ```http POST /v1/tasks/{id}/answer ``` Gives the agent the value it asked for when the task is waiting with a pending question. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | Field | Type | Description | | --- | --- | --- | | `key` | string | The pending.key of the question | | `value` (required) | string | | ```json Request { "key": "policy_holder_phone", "value": "+351 912 345 678" } ``` ## Approve or refuse a step ```http POST /v1/tasks/{id}/approve ``` Answers a pending approval: the agent goes on with approve true, and stops that step with approve false. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | Field | Type | Description | | --- | --- | --- | | `approve` (required) | boolean | | | `by` | string | Who decided, kept with the proof | ## Cancel a task ```http POST /v1/tasks/{id}/cancel ``` Stops a task that is queued, running, waiting or paused. A cancelled task is never billed. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | ## Run a task again ```http POST /v1/tasks/{id}/retry ``` Creates a new task with the same input as a finished one. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | ## Follow a task live ```http GET /v1/tasks/{id}/stream ``` Server-Sent Events: task when its state changes, step for each action of the agent, screenshot for each image, done at the end. Send Last-Event-ID to resume after the last step. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | `Last-Event-ID` | header | | ## Get the proof ```http GET /v1/tasks/{id}/proof ``` Every step of the agent and the screenshots it saw, kept 90 days. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | ## Delete the proof ```http DELETE /v1/tasks/{id}/proof ``` Erases the steps and screenshots of a finished task now. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | ## Download a file ```http GET /v1/tasks/{id}/files/{name} ``` A file the site gave during the task, listed in task.files. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | `name` | path | | ## Dispute a billed task ```http POST /v1/tasks/{id}/dispute ``` Asks for a check of a billed task whose result is wrong. The proof is reviewed and the price refunded when the claim is right. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Task id, like tsk_9f2c41a07b3d5e18 | | Field | Type | Description | | --- | --- | --- | | `reason` (required) | string | | --- Source: https://hapti.dev/docs/api-catalogue # Catalogue API > Reference of the Hapti catalogue endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## List templates ```http GET /v1/catalogue ``` Ready-made tasks: give a template id and its params instead of a url and a goal. | Parameter | In | Description | | --- | --- | --- | | `lang` | query | en or fr | ```json Response 200 { "object": "list", "data": [ { "id": "prendre_rdv", "group": "demarches", "name": "Book an appointment", "description": "On a booking site (prefecture, town hall, doctor…), books the first slot that fits.", "params": { "site": "address of the booking page", "reason": "reason for the appointment", "window": "preferred dates and times (optional)" } } ] } ``` --- Source: https://hapti.dev/docs/api-batches # Batches API > Reference of the Hapti batches endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Create a batch ```http POST /v1/batches ``` Many tasks at once, from a list of tasks or from one template and a list of items. | Parameter | In | Description | | --- | --- | --- | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | | Field | Type | Description | | --- | --- | --- | | `name` | string | | | `webhook` | string | | | `tasks` | array | | | `template` | TaskInput | | | `items` | array | | ```json Response 201 { "id": "bat_344f0b5bbdb6853e", "object": "batch", "mode": "test", "name": "November invoices", "total": 2, "done": 0, "counts": { "queued": 2, "paused": 0, "running": 0, "waiting": 0, "succeeded": 0, "failed": 0, "blocked": 0, "incomplete": 0, "needs_person": 0, "cancelled": 0 }, "billed_cents": 0, "created_at": "2026-11-22T18:40:56.210Z", "finished_at": null, "cancelled": false } ``` ## List batches ```http GET /v1/batches ``` Batches, newest first. | Parameter | In | Description | | --- | --- | --- | | `limit` | query | Up to 100 | ## Get a batch ```http GET /v1/batches/{id} ``` Counts per status and what was billed. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Batch id | ## List the tasks of a batch ```http GET /v1/batches/{id}/tasks ``` Paged with after and next. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Batch id | | `status` | query | Filter by status | | `after` | query | next of the previous page | | `limit` | query | Up to 200 | ## Cancel a batch ```http POST /v1/batches/{id}/cancel ``` Cancels every task of the batch that is not over. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Batch id | --- Source: https://hapti.dev/docs/api-schedules # Schedules API > Reference of the Hapti schedules endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Create a schedule ```http POST /v1/schedules ``` Runs the same task on a cron or every interval, in a time zone. | Parameter | In | Description | | --- | --- | --- | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | | Field | Type | Description | | --- | --- | --- | | `task` (required) | TaskInput | | | `cron` | string | | | `every` | string | | | `timezone` | string | | | `name` | string | | | `start_at` | string | | | `until` | string | | | `run_now` | boolean | | ```json Response 201 { "id": "sch_f23abc98afc7afcc", "object": "schedule", "mode": "test", "name": "Monday report", "every": null, "cron": "0 8 * * 1", "timezone": "Europe/Lisbon", "paused": false, "next_run_at": "2026-11-23T08:00:00.000Z", "until": null, "runs": 0, "last_task": null, "last_run_at": null, "last_error": null, "task": { "url": "https://portal.example.com/reports", "goal": "Download the weekly report." }, "created_at": "2026-11-22T18:40:56.222Z" } ``` ## List schedules ```http GET /v1/schedules ``` Every schedule of the mode. ## Get a schedule ```http GET /v1/schedules/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Schedule id | ## Pause or resume a schedule ```http PATCH /v1/schedules/{id} ``` Send paused true or false. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Schedule id | | Field | Type | Description | | --- | --- | --- | | `paused` | boolean | | ## Delete a schedule ```http DELETE /v1/schedules/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Schedule id | ## List the tasks of a schedule ```http GET /v1/schedules/{id}/tasks ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Schedule id | --- Source: https://hapti.dev/docs/api-users # Users API > Reference of the Hapti users endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Create a person ```http POST /v1/users ``` Registers a person you act for, with their country, language and time zone. Tasks with the same user share one device, one session and one memory. | Field | Type | Description | | --- | --- | --- | | `id` (required) | string | | | `name` | string | | | `country` | string | | | `locale` | string | | | `timezone` | string | | | `mandate` | Mandate | | ```json Response 201 { "object": "user", "id": "customer_42", "name": "Ana Silva", "created_at": "2026-11-22T18:40:56.163Z", "mandate": null, "session": null, "device": { "locale": "pt-PT", "timezone": "Europe/Lisbon", "country": "pt", "country_set": true, "since": "2026-11-22T18:40:56.165Z" }, "limits": null, "accounts": [] } ``` ## List people ```http GET /v1/users ``` | Parameter | In | Description | | --- | --- | --- | | `limit` | query | Up to 100 | | `q` | query | Search | | `cursor` | query | next_cursor of the previous page | ## Get a person ```http GET /v1/users/{user} ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Update a person ```http PATCH /v1/users/{user} ``` Name, country, language, time zone and limits. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `name` | string | | | `country` | string | | | `locale` | string | | | `timezone` | string | | | `limits` | object | | ## Forget a person ```http DELETE /v1/users/{user} ``` Erases the person: session, memory, stored accounts, mandate, inbox and received messages. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Give a mandate ```http POST /v1/users/{user}/mandate ``` Records what the agent may do for the person without asking each time, and who agreed to it. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `scope` (required) | string | What the agent may do for the person. | | `given_by` (required) | string | Who gave it, or how the person agreed. | | `sites` | array | | | `until` | string | | ```json Response 200 { "mandate": { "scope": "Declare insurance claims and download invoices", "sites": [], "given_by": "Ana Silva, in the app on 2026-11-20", "until": null, "given_at": "2026-11-22T18:40:56.233Z" } } ``` ## Revoke the mandate ```http DELETE /v1/users/{user}/mandate ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## List stored accounts ```http GET /v1/users/{user}/accounts ``` Accounts the agent may sign in with for this person. Secrets are never returned. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Store an account ```http PUT /v1/users/{user}/accounts/{account} ``` Saves sign-in details in the vault, sealed. The agent types them in the browser; the model never sees them. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | `account` | path | | | Field | Type | Description | | --- | --- | --- | | `origin` (required) | string | | | `username` | string | | | `password` (required) | string | | | `totp_secret` | string | | ```json Response 200 { "account": "insurer", "label": "insurer", "origin": "https://portal.example.com", "has_username": true, "has_totp": false, "entered_by": "developer", "updated_at": "2026-11-22T18:40:56.235Z" } ``` ## Delete an account ```http DELETE /v1/users/{user}/accounts/{account} ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | `account` | path | | ## Create a connect link ```http POST /v1/users/{user}/connect ``` A page where the person enters their own sign-in details. You never see them. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `accounts` | array | | | `brand` | string | | | `return_url` | string | | | `expires_in` | integer | | ## Revoke connect links ```http DELETE /v1/users/{user}/connect ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Read the memory ```http GET /v1/users/{user}/memory ``` Lasting facts the agent kept about the person, never secrets. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Add a fact ```http POST /v1/users/{user}/memory ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `fact` (required) | string | | ## Erase the memory ```http DELETE /v1/users/{user}/memory ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Open an email inbox ```http POST /v1/users/{user}/inbox ``` An address that receives the emails sites send to the person, such as confirmation codes, which the agent reads by itself. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `username` | string | | | `domain` | string | | | `client_id` | string | | ## List inboxes ```http GET /v1/users/{user}/inbox ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## List received emails ```http GET /v1/users/{user}/emails ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | `since` | query | ISO date | | `limit` | query | Up to 100 | ## Give a phone number ```http POST /v1/users/{user}/phone ``` A real number that receives the texts sites send. Live keys only, paid monthly from the credit. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | Field | Type | Description | | --- | --- | --- | | `country` | string | | ## Get the phone number ```http GET /v1/users/{user}/phone ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Release the phone number ```http DELETE /v1/users/{user}/phone ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## List received texts ```http GET /v1/users/{user}/sms ``` | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | ## Usage of a person ```http GET /v1/users/{user}/usage ``` Tasks and amounts billed for this person. | Parameter | In | Description | | --- | --- | --- | | `user` | path | Your own id for the person, like customer_42 | | `from` | query | YYYY-MM-DD | | `to` | query | YYYY-MM-DD | --- Source: https://hapti.dev/docs/api-webhooks # Webhooks API > Reference of the Hapti webhooks endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Create an endpoint ```http POST /v1/webhooks/endpoints ``` An https address that receives the events you choose, signed with its own secret. The secret is returned once here. | Parameter | In | Description | | --- | --- | --- | | `Idempotency-Key` | header | Any unique string of 1 to 255 visible characters. The same key with the same request within 24 hours returns the first answer again instead of acting twice. | | Field | Type | Description | | --- | --- | --- | | `url` | string | | | `events` | array | Event types, a family like user.*, or ["*"] for every event, including future ones. | | `description` | string | | | `headers` | object | Up to 10 headers sent with each delivery. | | `enabled` | boolean | | ```json Response 201 { "id": "we_0e47caf33717b1a8", "object": "webhook_endpoint", "url": "https://api.example.com/hooks/hapti", "events": [ "task.succeeded", "task.failed", "task.waiting" ], "description": "Production", "enabled": true, "disabled_reason": null, "disabled_at": null, "failing_since": null, "last_success_at": null, "headers": {}, "mode": "test", "secret": "whsec_0f9c3a…", "previous_secret_expires_at": null, "created_at": "2026-11-22T18:40:56.225Z" } ``` ## List endpoints ```http GET /v1/webhooks/endpoints ``` With their deliveries and failures of the last 7 days. ## Get an endpoint ```http GET /v1/webhooks/endpoints/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | ## Update an endpoint ```http PATCH /v1/webhooks/endpoints/{id} ``` Address, events, description, headers, or enabled to pause and resume. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | | Field | Type | Description | | --- | --- | --- | | `url` | string | | | `events` | array | Event types, a family like user.*, or ["*"] for every event, including future ones. | | `description` | string | | | `headers` | object | Up to 10 headers sent with each delivery. | | `enabled` | boolean | | ## Delete an endpoint ```http DELETE /v1/webhooks/endpoints/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | ## Reveal the secret ```http GET /v1/webhooks/endpoints/{id}/secret ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | ## Roll the secret ```http POST /v1/webhooks/endpoints/{id}/roll-secret ``` A new secret; the previous one stays valid for expires_in_hours (24 by default, 0 to 168) and each delivery carries both signatures meanwhile. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | | Field | Type | Description | | --- | --- | --- | | `expires_in_hours` | integer | | ## Send a test event ```http POST /v1/webhooks/endpoints/{id}/test ``` Sends a signed ping event now and returns the delivery with the answer of your server. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | ## Send missed events again ```http POST /v1/webhooks/endpoints/{id}/recover ``` Sends once every event of the period that never reached this endpoint. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Webhook endpoint id | | Field | Type | Description | | --- | --- | --- | | `since` | string | 3 days ago by default, at most 30 | ## Reveal the organisation secret ```http GET /v1/webhook/secret ``` The secret that signs the deliveries of webhooks given on a task or a batch with the webhook field. ## List event types ```http GET /v1/webhooks/events ``` ## List deliveries ```http GET /v1/webhooks/deliveries ``` | Parameter | In | Description | | --- | --- | --- | | `endpoint` | query | Endpoint id | | `event` | query | Event type | | `state` | query | pending, delivered or failed | | `limit` | query | Up to 100 | | `cursor` | query | next_cursor of the previous page | ## Get a delivery ```http GET /v1/webhooks/deliveries/{id} ``` With every attempt, the answer of your server and the body sent. | Parameter | In | Description | | --- | --- | --- | | `id` | path | Delivery id | ## Send a delivery again ```http POST /v1/webhooks/deliveries/{id}/resend ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Delivery id | --- Source: https://hapti.dev/docs/api-events # Events API > Reference of the Hapti events endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## List events ```http GET /v1/events ``` Every event of the last 30 days, the same objects webhooks send. | Parameter | In | Description | | --- | --- | --- | | `type` | query | An event type, or a family like task.* | | `object` | query | Only the events of this task or object id | | `since` | query | ISO date | | `limit` | query | Up to 100 | | `cursor` | query | next_cursor of the previous page | ```json Response 200 { "object": "list", "data": [ { "id": "evt_c3b9a22cc8666f754e930055", "object": "event", "type": "task.succeeded", "api_version": "2026-11-22", "created_at": "2026-11-22T18:40:56.191Z", "mode": "test", "data": { "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" } } ], "has_more": false, "next_cursor": null, "total": 1 } ``` ## Get an event ```http GET /v1/events/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Event id | ## Follow every task live ```http GET /v1/stream ``` Server-Sent Events: a task event each time a task of the mode changes state. --- Source: https://hapti.dev/docs/api-recipes # Recipes API > Reference of the Hapti recipes endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## List recipes ```http GET /v1/recipes ``` Tasks learnt from successes and replayed faster and cheaper. ## Get a recipe ```http GET /v1/recipes/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Recipe id | ## Rename a recipe ```http PATCH /v1/recipes/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Recipe id | | Field | Type | Description | | --- | --- | --- | | `name` | string | | ## Delete a recipe ```http DELETE /v1/recipes/{id} ``` | Parameter | In | Description | | --- | --- | --- | | `id` | path | Recipe id | --- Source: https://hapti.dev/docs/api-account # Account API > Reference of the Hapti account endpoints: parameters, fields and real responses. Every endpoint takes a key in the Authorization header: `Authorization: Bearer hp_test_...`. Base address: `https://api.hapti.dev`. The full specification is in [openapi.json](/openapi.json). ## Who am I ```http GET /v1/me ``` The organisation and mode of the key. ## Credit and prices ```http GET /v1/billing ``` The credit left and the prices. ## Usage by day ```http GET /v1/usage ``` | Parameter | In | Description | | --- | --- | --- | | `from` | query | YYYY-MM-DD | | `to` | query | YYYY-MM-DD | ## Usage by person ```http GET /v1/usage/users ``` | Parameter | In | Description | | --- | --- | --- | | `from` | query | YYYY-MM-DD | | `to` | query | YYYY-MM-DD | ## API versions ```http GET /v1/versions ``` Every version and what it changed, with the one your organisation is pinned to. ```json Response 200 { "object": "list", "latest": "2026-11-22", "pinned": "2026-11-22", "current": "2026-11-22", "data": [ { "id": "2026-11-22", "changes": [ "A live task without enough credit is created paused and starts by itself once credit is added (on_insufficient_credit: refuse keeps the 402).", "Lists are paged with has_more, next_cursor and total.", "price_cents is what was billed, 0 until a live task succeeds; starting_price_cents gives the starting price." ] }, { "id": "2026-11-01", "changes": [ "A live task without enough credit is refused with 402 insufficient_credit." ] } ] } ``` ## List API requests ```http GET /v1/logs ``` Every request made with a key of the mode in the last 30 days, secrets masked. | Parameter | In | Description | | --- | --- | --- | | `status` | query | ok or error | | `q` | query | Path or Request-Id | | `limit` | query | Up to 100 | | `cursor` | query | next_cursor of the previous page |