# Toyroom API

> Domain intelligence API from toyroom.ai: appraisal, classification, keyword counts across 390M+ registered domains, RDAP, DNS. REST (https://api.toyroom.ai/v1) and MCP (https://api.toyroom.ai/mcp) share one bearer key and one daily credit quota.

Every request needs `Authorization: Bearer trm_live_...`. Bodies are JSON objects. Lists have per-endpoint maximums. 429 responses carry Retry-After. 502 responses are not charged and are safe to retry. Zone endpoints return counts, never domain names.

## Docs

- [Full reference (markdown)](https://api.toyroom.ai/llms-full.txt): every endpoint with request fields, examples, response fields, limits, errors, MCP setup.
- [OpenAPI 3.1](https://api.toyroom.ai/openapi.json): machine-readable schema of the REST surface.
- [Developer portal](https://api.toyroom.ai/): the same content as a web page.

## Endpoints

- [POST /v1/appraise](https://api.toyroom.ai/llms-full.txt#post-v1appraise): Value estimate for one domain from the Toyroom v2.1 model. Cost: 1 credit.
- [POST /v1/appraise/bulk](https://api.toyroom.ai/llms-full.txt#post-v1appraisebulk): Value estimates for up to 500 domains in one request. Cost: 1 credit per domain.
- [POST /v1/categorize](https://api.toyroom.ai/llms-full.txt#post-v1categorize): Industry vertical and subcategory for up to 100 domains. Cost: 2 credits per domain.
- [POST /v1/camelcase](https://api.toyroom.ai/llms-full.txt#post-v1camelcase): Word splits for up to 1,000 domains: cloudkitchen.com becomes CloudKitchen.com. Cost: 1 credit.
- [POST /v1/zone/count](https://api.toyroom.ai/llms-full.txt#post-v1zonecount): How many registered domains contain, start with, or end with a keyword. Cost: 2 credits.
- [POST /v1/zone/lookup](https://api.toyroom.ai/llms-full.txt#post-v1zonelookup): Zone facts for up to 5,000 names per request: is it registered, and in how many extensions. Cost: 1 credit per 10 names.
- [GET /v1/zone/stats](https://api.toyroom.ai/llms-full.txt#get-v1zonestats): Size, freshness, and largest extensions of the current zone index. Cost: 1 credit.
- [POST /v1/rdap](https://api.toyroom.ai/llms-full.txt#post-v1rdap): Registrar, dates, status flags, and nameservers for up to 10 domains via RDAP. Cost: 2 credits per domain.
- [POST /v1/dns](https://api.toyroom.ai/llms-full.txt#post-v1dns): Live DNS records for up to 50 domains. Cost: 1 credit per domain.
- [POST /v1/jobs](https://api.toyroom.ai/llms-full.txt#post-v1jobs): Queue up to 1,000,000 names for zone lookup, appraisal, or categorization. Cost: reserved at submit.
- [GET /v1/jobs/{job_id}](https://api.toyroom.ai/llms-full.txt#get-v1jobs{job_id}): Status, progress, timing, and the results URL once rows exist. Cost: free.
- [GET /v1/jobs/{job_id}/results](https://api.toyroom.ai/llms-full.txt#get-v1jobs{job_id}results): One file, rows in input order: NDJSON by default, CSV with ?format=csv. Cost: free.
- [GET /v1/jobs](https://api.toyroom.ai/llms-full.txt#get-v1jobs): Your 50 most recent jobs and the names you have in flight. Cost: free.
- [DELETE /v1/jobs/{job_id}](https://api.toyroom.ai/llms-full.txt#delete-v1jobs{job_id}): Stop a queued or running job, or remove a finished job's file early. Cost: free.
- [GET /v1/usage](https://api.toyroom.ai/llms-full.txt#get-v1usage): Credits used today, by endpoint, plus your limits. Cost: free.
- [GET /v1/ping](https://api.toyroom.ai/llms-full.txt#get-v1ping): Confirms the key is valid and returns its name. Cost: free.

## MCP

- [MCP server](https://api.toyroom.ai/mcp): streamable HTTP, stateless, tools: appraise_domain, appraise_bulk, categorize_domains, zone_count, zone_lookup, submit_job, job_status, job_results, rdap_lookup, dns_lookup.

## Optional

- [toyroom.ai](https://toyroom.ai): the interactive tools built on the same data.
- Contact: feedback@toyroom.ai