Numbers API — Cursor agent contract

docs.md docs.json llms.txt Login

Public page. No API key and no login. Another Cursor agent should fetch /docs.md or /docs.json and follow them exactly.

For Cursor agents Origin https://onlygirls.click. Read this page without a key. Never invent nk_.... Never buy a real number in tests — use country=ger. SMS methods always return HTTP 200. getNumberSelected success is JSON; everything else is text/plain. FastAPI Swagger is disabled: /docs is this contract.

Auth

Surface	Auth	Notes
SMS methods	`nk_...` as `x-api-key` or `api_key=`	Invalid key → plaintext `BAD_KEY` (HTTP 200). No `Authorization: Bearer`.
Monitor UI / `/api/state` / `/api/selected`	login cookie	API keys do not work. Agents must use `getNumberSelected`, not `/api/selected`.

Key resolution order: header x-api-key, then query api_key, then body api_key. Keys are created in /admin. This page never returns keys.

SMS entrypoints

GET and POST are the same. Query, JSON, urlencoded, and multipart are merged; non-empty query wins. Origin: https://onlygirls.click

/stubs/handler_api.php
/handler_api.php
/api/handler
/api/getNumberSelected — only getNumberSelected, no action needed

Unknown action → BAD_ACTION.

getNumber

Issue a number. Params: action=getNumber service country (ISO2 lowercase) optional operator (empty → any).

ACCESS_NUMBER:<activation_id>:<phone>
NO_NUMBERS
BAD_KEY

activation_id is 24 lowercase hex. Use it as id later. Safe probe that does not buy a number: country=ger → NO_NUMBERS.

GET /stubs/handler_api.php?api_key=KEY&action=getNumber&service=ig&operator=any&country=ger

getNumberSelected

Random checked operator from the monitor, then buys a number for that country with that operator name. Preferred when checkboxes are set. Unknown or empty selection → NO_NUMBERS.

Success is JSON. Errors stay plaintext.

{
  "issue_id": "...",
  "issued_at": "...",
  "service": "ig",
  "id": "86|TIM - Telecom Italia S.p.A.|0",
  "country_id": 86,
  "code": "IT",
  "country_name": "Italy",
  "operator": "TIM - Telecom Italia S.p.A.",
  "rate": 238,
  "activation_id": "6aafd036afdd2a1cdba26133",
  "phone": "393925063783"
}

field	use
`activation_id`	local id for `getStatus` / `setStatus`
`phone`	digits, no `+`
`issue_id`	monitor stats only — do not send it back
`operator`	display name already sent to the partner
`code`	ISO2 uppercase in this JSON

Optional service limits the pool. Shortcut: GET/POST /api/getNumberSelected.

GET /api/getNumberSelected?api_key=KEY&service=ig
POST /api/getNumberSelected  x-api-key: KEY  {"service":"ig"}

getStatus

action=getStatus id=<activation_id>. Partner text is forwarded. Unknown local id → NO_ACTIVATION.

STATUS_WAIT_CODE
STATUS_OK:<sms_code>
ACCESS_CANCEL
NO_ACTIVATION
BAD_ACTION
BAD_KEY

STATUS_OK:852508 means the SMS code is 852508.

setStatus

action=setStatus id status. Missing status → BAD_STATUS.

status	meaning	typical body
`1`	ready	`ACCESS_READY`
`6`	sent	`ACCESS_ACTIVATION`
`-1` or `8`	cancel	`ACCESS_CANCEL`
`10`	other fail	partner text

If you accidentally buy a number, cancel with status=-1.

Stats (monitor only)

Written once per getNumberSelected issue. Later status calls do not overwrite. No status for 10 minutes → fail_other.

event	column
number issued	issued
`getStatus` `STATUS_OK`	success
`NO_ACTIVATION` / `ACCESS_CANCEL` / cancel `-1` or `8`	fail
`setStatus 10` or 10-minute timeout	fail_other

Agent rules

Do not invent API keys. Ask the human for nk_....
Do not buy real numbers in tests. Use country=ger or unknown ids.
If you get ACCESS_NUMBER by accident, setStatus status=-1.
Always reuse the local 24-hex id, never an upstream id.
Monitor JSON APIs need a login cookie; they reject API keys.
Do not call partner hosts. Only this origin.

Suggested flow

GET /stubs/handler_api.php?api_key=KEY&action=getNumber&service=ig&country=ger
→ NO_NUMBERS (key ok) or BAD_KEY

GET /api/getNumberSelected?api_key=KEY&service=ig
→ JSON activation_id, phone   (only if the human asked to buy)

GET ...&action=getStatus&id=activation_id
→ STATUS_WAIT_CODE | STATUS_OK:code | ACCESS_CANCEL

GET ...&action=setStatus&id=activation_id&status=-1

Out of scope

/api/state /api/selected /api/result /api/refresh /api/messages /api/codes /api/selection /api/admin/* /api/health UI / /admin.

Machine copies: /docs.md · /docs.json · /llms.txt