API v1 · preview

Documentation

Public to read, authenticated to execute. The same evidence and quota semantics apply to browser sessions, REST, CLI, and MCP.

Create an API key OpenAPI 3.1

Quickstart

Your first protected request

Send user keys only in the Bearer header. Use one idempotency key per logical POST.

export NAMING_SIGNAL_API_KEY="your-user-key"

curl -sS "https://namingsignal.com/api/v1/check" \
  -H "Authorization: Bearer $NAMING_SIGNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: check-$(date +%s)" \
  -d '{"names":["offhook","nicless"],"tlds":["com","app"]}'

Contract

Endpoints and credit cost

10,000 free credits reset monthly

POST/api/v1/brief

Compile bounded context into an editable brief

10 credits per public import

POST/api/v1/generate

Generate one diverse batch of up to 50 names

500 credits

POST/api/v1/check

Check up to 150 name × TLD combinations

1 credit per combination

POST/api/v1/rank

Compare up to 30 survivors

500 credits

POST/api/v1/research

Research one to three finalists

250 credits per finalist

GET/api/v1/health

Inspect public provider and policy readiness

Free and public

Iterative naming

Generate from founder feedback

Keep the approved brief and sprint ID. Pass liked and disliked examples as signals, and exclude the complete prior name ledger. Run the returned names through the normal check and rank endpoints before merging them into the project.

curl -sS "https://namingsignal.com/api/v1/generate" \
  -H "Authorization: Bearer $NAMING_SIGNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: iteration-$(date +%s)" \
  -H "X-Name-Ledger-Sprint: my-project-001" \
  -d '{
    "brief": { "product": "...approved brief fields..." },
    "count": 40,
    "tlds": ["com", "app"],
    "checkPrimaryDomain": false,
    "excludedNames": ["every", "prior", "name"],
    "iteration": {
      "feedback": "Keep the direct optimism. Explore release and momentum metaphors.",
      "likedNames": ["Offhook"],
      "dislikedNames": ["Clinical Core"]
    }
  }'

CLI

Local context, hosted evidence

export NAMING_SIGNAL_API_KEY="your-user-key"
npm run --silent cli -- research offhook \
  --brief naming-brief.json

The CLI keeps repository selection local and sends only the approved bounded context.

stdio MCP

Environment-based credentials

[mcp_servers.naming_signal]
command = "npm"
args = ["--prefix", "/absolute/path/to/product", "run", "--silent", "mcp"]

[mcp_servers.naming_signal.env]
NAMING_SIGNAL_API_URL = "https://namingsignal.com"
NAMING_SIGNAL_API_KEY = "your-user-key"

Call check_names for a small smoke test after restarting the agent.

Agent handoff

Ready-to-paste instruction

Use NamingSignal for this naming task. First read https://namingsignal.com/agent-guide.txt and https://namingsignal.com/openapi.json. Use https://namingsignal.com/api/v1/health for public service discovery. For protected REST calls, read NAMING_SIGNAL_API_KEY from the local environment and send it as "Authorization: Bearer $NAMING_SIGNAL_API_KEY"; never print, log, commit, or ask me to paste the secret into chat. If the variable is missing, ask me to create a free key at https://namingsignal.com/developers/keys and set it locally. Use one unique Idempotency-Key per logical POST and one X-Name-Ledger-Sprint value across a sprint. For feedback rounds, pass the founder's instruction plus likedNames and dislikedNames in generate.iteration, and pass the complete prior ledger in excludedNames. Preserve the complete evidence ledger, uncertainty, sources, timestamps, feedback rounds, usage, and quota data. Never describe RDAP not-found as guaranteed availability and never claim trademark clearance.

Evidence semantics

Not-found is evidence, not a guarantee

confirmed

A direct source returned decisive registered or exact-match evidence.

inferred

A calibrated registry not-found suggests likely unregistered at the check time.

unknown

Timeouts, blocks, unsupported providers, and conflicts stay unresolved.

manual

A person must recheck current price, registrability, social access, or legal risk.