Docs Sign in Get a key

Docs / API reference

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.

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.

FieldTypeDescription
id (required)string
namestring
countrystring
localestring
timezonestring
mandateMandate
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
ParameterInDescription
limitqueryUp to 100
qquerySearch
cursorquerynext_cursor of the previous page

Get a person

HTTP
GET /v1/users/{user}
ParameterInDescription
userpathYour own id for the person, like customer_42

Update a person

HTTP
PATCH /v1/users/{user}

Name, country, language, time zone and limits.

ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
namestring
countrystring
localestring
timezonestring
limitsobject

Forget a person

HTTP
DELETE /v1/users/{user}

Erases the person: session, memory, stored accounts, mandate, inbox and received messages.

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

ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
scope (required)stringWhat the agent may do for the person.
given_by (required)stringWho gave it, or how the person agreed.
sitesarray
untilstring
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
ParameterInDescription
userpathYour 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.

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

ParameterInDescription
userpathYour own id for the person, like customer_42
accountpath
FieldTypeDescription
origin (required)string
usernamestring
password (required)string
totp_secretstring
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}
ParameterInDescription
userpathYour own id for the person, like customer_42
accountpath
HTTP
POST /v1/users/{user}/connect

A page where the person enters their own sign-in details. You never see them.

ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
accountsarray
brandstring
return_urlstring
expires_ininteger
HTTP
DELETE /v1/users/{user}/connect
ParameterInDescription
userpathYour 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.

ParameterInDescription
userpathYour own id for the person, like customer_42

Add a fact

HTTP
POST /v1/users/{user}/memory
ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
fact (required)string

Erase the memory

HTTP
DELETE /v1/users/{user}/memory
ParameterInDescription
userpathYour 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.

ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
usernamestring
domainstring
client_idstring

List inboxes

HTTP
GET /v1/users/{user}/inbox
ParameterInDescription
userpathYour own id for the person, like customer_42

List received emails

HTTP
GET /v1/users/{user}/emails
ParameterInDescription
userpathYour own id for the person, like customer_42
sincequeryISO date
limitqueryUp 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.

ParameterInDescription
userpathYour own id for the person, like customer_42
FieldTypeDescription
countrystring

Get the phone number

HTTP
GET /v1/users/{user}/phone
ParameterInDescription
userpathYour own id for the person, like customer_42

Release the phone number

HTTP
DELETE /v1/users/{user}/phone
ParameterInDescription
userpathYour own id for the person, like customer_42

List received texts

HTTP
GET /v1/users/{user}/sms
ParameterInDescription
userpathYour 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.

ParameterInDescription
userpathYour own id for the person, like customer_42
fromqueryYYYY-MM-DD
toqueryYYYY-MM-DD