Docs Sign in Get a key

Docs / API reference

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.

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.

ParameterInDescription
Idempotency-KeyheaderAny 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.
FieldTypeDescription
urlstringThe page to start on.
goalstringWhat to achieve and what to report back, in plain words, in any language.
dataobjectThe facts the agent may use. It never invents a missing value: it asks.
templatestringA catalogue template id, instead of url and goal.
paramsobjectThe params of the template.
userstringThe person the task acts for. Gives the task their device, session, memory, inbox and stored accounts.
accountsarrayStored accounts of the person the agent may sign in with.
outputobjectA JSON Schema for result.data. A task whose answer cannot follow it is not billed.
filesarrayFiles the agent may upload on the site: up to 20, 50 MB each, 100 MB in all.
webhookstringAn https address that receives the events of this task only.
approvalstring: mandate, requiredrequired: the agent waits for your approval before any step that commits the person.
max_price_centsintegerThe agent stops before the price would go over it.
max_stepsinteger
answer_languagestringLanguage of the answer and questions, like fr, pt-BR or wo. By default, the language of the goal.
localestringLanguage of the browser, like pt-PT.
countrystringTwo letters: the country the sites see the person in.
proxybooleanGo out through a residential address in that country, billed per GB when the task succeeds.
memorybooleantrue by default with a user.
keep_sessionbooleantrue by default with a user.
learnbooleantrue by default: a success becomes a recipe.
recipestringA recipe id to replay.
on_insufficient_creditstring: pause, refusepause by default: a live task without enough credit waits and starts once credit is added.
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"
}
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.

ParameterInDescription
limitquery1 to 100, 25 by default
cursorquerynext_cursor of the previous page
statusqueryOne status or several separated by commas
userqueryOnly the tasks of this person
qquerySearch the goal, the site, the person or the id
sincequeryISO date
untilqueryISO date
templatequeryCatalogue template id
batchqueryBatch id
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.

FieldTypeDescription
urlstringThe page to start on.
goalstringWhat to achieve and what to report back, in plain words, in any language.
dataobjectThe facts the agent may use. It never invents a missing value: it asks.
templatestringA catalogue template id, instead of url and goal.
paramsobjectThe params of the template.
userstringThe person the task acts for. Gives the task their device, session, memory, inbox and stored accounts.
accountsarrayStored accounts of the person the agent may sign in with.
outputobjectA JSON Schema for result.data. A task whose answer cannot follow it is not billed.
filesarrayFiles the agent may upload on the site: up to 20, 50 MB each, 100 MB in all.
webhookstringAn https address that receives the events of this task only.
approvalstring: mandate, requiredrequired: the agent waits for your approval before any step that commits the person.
max_price_centsintegerThe agent stops before the price would go over it.
max_stepsinteger
answer_languagestringLanguage of the answer and questions, like fr, pt-BR or wo. By default, the language of the goal.
localestringLanguage of the browser, like pt-PT.
countrystringTwo letters: the country the sites see the person in.
proxybooleanGo out through a residential address in that country, billed per GB when the task succeeds.
memorybooleantrue by default with a user.
keep_sessionbooleantrue by default with a user.
learnbooleantrue by default: a success becomes a recipe.
recipestringA recipe id to replay.
on_insufficient_creditstring: pause, refusepause by default: a live task without enough credit waits and starts once credit is added.
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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
FieldTypeDescription
keystringThe pending.key of the question
value (required)string
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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
FieldTypeDescription
approve (required)boolean
bystringWho 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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
Idempotency-KeyheaderAny 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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
Idempotency-KeyheaderAny 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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
Last-Event-IDheader

Get the proof

HTTP
GET /v1/tasks/{id}/proof

Every step of the agent and the screenshots it saw, kept 90 days.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18

Delete the proof

HTTP
DELETE /v1/tasks/{id}/proof

Erases the steps and screenshots of a finished task now.

ParameterInDescription
idpathTask 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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
namepath

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.

ParameterInDescription
idpathTask id, like tsk_9f2c41a07b3d5e18
FieldTypeDescription
reason (required)string