# HelpfulAI for developers

HelpfulAI agents already answer the phone, read and send email and keep an appointment calendar.
This API lets your own software do those things on an agent's behalf: quote and order an exact
phone number, receive each inbound text, call and email as an event, send the reply to a mailbox
message, and book or cancel appointments on the agent's calendar.

The [API reference](/api) is generated from the same OpenAPI document the servers are checked
against, so every operation, request body and response there is current. The raw document is
served at [`/openapi.json`](/openapi.json) for code generators and agents.

## Sign in

Use the account you already have on [helpfulai.app](https://helpfulai.app), with email and
password or with Google. Nothing here needs a separate developer account.

## Create an API key

[API keys](/settings/api-keys) is the first item in the header. A key belongs to an organization,
so your account has to be an admin or manager of one. Give the key a name you will recognize in a
year and, if you want, an expiry of up to ten years.

The full key is shown once, in the tab where you created it. Copy it then. HelpfulAI stores only a
hash, so after a reload the page shows the `hpx_…` prefix and nothing else can recover the key.
Roll a key to get a new one with the same name; revoke a key the moment you suspect it leaked.

Every key carries both scopes the platform issues today: `acp` for the agent communications API
on this site and `awcp` for agent work coordination.

## Call the API

Send the key as a bearer token. Each key may make 120 requests a minute per scope. Keep the key
in your environment or a secrets manager, never in a command you paste into a shared shell history.

```bash
export HELPFULAI_API_KEY="hpx_…"   # the key you copied when it was created

curl https://bqrrisyunrqjqefgvncr.supabase.co/functions/v1/avatar-phone-quote \
  -H "Authorization: Bearer $HELPFULAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "...": "see the operation in the API reference" }'
```

:::note

Each operation in the reference lists the credentials it accepts under **Security**. The agent
phone, email and calendar APIs are opening to developer keys operation by operation; an operation
that still lists only a signed-in user's token or a webhook signature is not callable with an
`hpx_` key yet.

:::

Base URL: `https://bqrrisyunrqjqefgvncr.supabase.co/functions/v1`. Requests are `POST` with a JSON
body unless the reference says otherwise. Errors are `{ "error": string, "code"?: string }`.