# JustCallMe

> JustCallMe lets a coding agent phone its human when it is blocked on a decision. The agent sends one question over HTTPS, the service rings the human's verified phone, a voice agent talks it through, and the agent polls for the confirmed answer. Base URL: https://justcallme.dev

## If you are an AI agent reading this

You can use JustCallMe right now if you have an API key. You cannot create an account yourself: sign-up needs a phone number verified by a text code, and only your human can do that.

- If `JUSTCALLME_API_KEY` is set in your environment, or a key was given to you, go straight to the API in the quickstart below.
- If you have no key, ask your human to open https://justcallme.dev/app, sign in with their phone number, and press "Copy API key" (or "Copy setup for my agent"). Then continue.
- Never put the key in a prompt, a commit or a log. Read it from the environment.
- Use it only for a decision you truly cannot make alone. Each call rings a real person and costs them minutes.

## Quickstart

1. Ask the question. Send a new `Idempotency-Key` UUID. Reuse the same UUID if you retry the same question, so the phone never rings twice.

```
curl -sS -X POST https://justcallme.dev/api/calls \
  -H "Authorization: Bearer $JUSTCALLME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"question":"Drop the v1 checkout endpoint in this PR?","context":"All 48 tests pass. v1 still gets ~3% of traffic.","choices":["Remove it now","Keep it one more release"]}'
```

The response is HTTP 201 with `{"id":"...","status":"waiting",...}`. Save the `id` with your task.

2. Poll every 3 seconds, for up to 180 seconds: `GET /api/calls/{id}` with the same Authorization header.
3. When `status` is `"answered"`, read `answer` (one of your `choices` if you gave any) and then `POST /api/calls/{id}/ack`. After the call ends the record also has `transcript`, the whole two-sided conversation. Read it, because the human may have added instructions beyond the choice.
4. Any other final status (`failed`, `expired`, `cancelled`) means there is no answer. Keep the task paused. Do not treat it as approval, and do not call again without a reason. If you lose track, `GET /api/calls/{id}` returns the same record.

## Rules that will bite you

- One open call per account. A second `POST /api/calls` while one is `waiting` returns 409. Wait for it or `POST /api/calls/{id}/cancel`.
- `question`: 3 to 1200 characters. `context`: up to 8000 characters, background for the voice agent, no secrets. `choices`: up to 8 strings of up to 200 characters. With `choices`, the answer is always one of them.
- Errors: 401 bad or revoked key, 402 the human is out of minutes (tell them to top up at https://justcallme.dev/pricing), 409 a call is already open or the idempotency key was reused for a different question, 429 rate limit.
- Calls last up to 120 connected seconds. Billing is by connected time, rounded up to 10 seconds, once per answered call. Unanswered calls are free.
- The server picks the recipient: the verified number on the account. You cannot choose or change it.
- An API key can reach only `/api/calls*` and `/api/me`. It cannot touch billing or the phone number.
- `GET /api/me` returns the account's remaining minutes and call history.

## Docs

- [Full reference for agents](https://justcallme.dev/llms-full.txt): every endpoint, field and status in one file.
- [OpenAPI 3.1 spec](https://justcallme.dev/openapi.json): machine-readable contract.
- [Agent skill file](https://justcallme.dev/skills/justcallme/SKILL.md): drop into a skills folder. Claude Code: `~/.claude/skills/justcallme/SKILL.md`. Codex: `~/.agents/skills/justcallme/SKILL.md`. OpenCode: `~/.config/opencode/skills/justcallme/SKILL.md`.
- [Developer docs](https://justcallme.dev/docs): the same material for humans.
- [Pricing](https://justcallme.dev/pricing): minute packs and plans.

## For the human

- [Dashboard: create an account, copy your API key, place a test call](https://justcallme.dev/app)