Namedesk
Guides

Appraisal API

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

Your AI assistant can do this too, with your team's key, through the Namedesk MCP server: it reads your team's reports and starts appraisals, and it sees each price before it spends.

Submit names

TerminalCode
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 name costs 10 credits and gets the full read: the appraisal, and a price band built on the AI signals. A name your team has already appraised comes back with 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 takes the same body and runs each name through a quick read first. A name the quick read judges not worth a full appraisal gets a short read and costs 1 credit. A name it judges worth appraising escalates to the full read and costs 10 credits, the same report a full job produces. Because any name may escalate, the job holds 10 credits up front for every name your team has not appraised before and refunds the difference as each name finishes; the final cost is 1 to 10 credits a name.

Poll the job

TerminalCode
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

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

The most recent report for the name in your team. 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. 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.

Last modified on