# Appraisal API

Submit one to a hundred domain names, poll until the job is done, then read each report. Every endpoint needs a key.

## Submit names

```bash
curl -X POST https://api.namedesk.app/v1/research-jobs \
  -H "x-api-key: $ND_KEY" \
  -H "content-type: application/json" \
  -d '{"domains": ["stripe.com", "linear.app"], "label": "October review"}'
```

Returns `202` with the job. Each uncached name costs 10 credits and gets the full read: the appraisal, the price band, the comparable sales. A name researched in the last 30 days is served from its existing report at no cost.

`label` is optional, up to 80 characters, and appears in the dashboard and the completion email.

## Quick reads

`POST /v1/research-jobs/quick` runs the same names through the quick read at 1 credit each. It never escalates to a full read.

## Poll the job

```bash
curl https://api.namedesk.app/v1/research-jobs/$JOB_ID -H "x-api-key: $ND_KEY"
```

Poll until every name has finished. `DELETE` the same path to cancel a running job; credits for names not yet processed come back.

## Read a report

```bash
curl https://api.namedesk.app/v1/report/stripe.com -H "x-api-key: $ND_KEY"
```

The most recent report for the name in your organisation. `GET /v1/research-jobs/{id}/report` returns every report in a job, and `/report/pricing` the price bands only. `GET /v1/domains/{domain}/pricing` reads the cached price band without a job.

The report's fields are listed in the [API reference](/api). Keys that are unknown for a name are left out rather than sent as `null`.

## Wallet

`GET /v1/wallet` returns your credit balance. Responses that spend credits, and a `402`, carry the new balance in the `X-Credit-Balance` header.

## Idempotency

Send `Idempotency-Key` on a `POST` and a retry with the same key returns the first response instead of charging twice.