canonical: https://jentic.com/apis/namingsignal.com/namingsignal

# NamingSignal API

The NamingSignal API turns a project description into a naming brief, generates batches of name candidates with a model ensemble, checks each name across domain TLDs and namespaces, ranks the survivors, and researches up to three finalists. Every model-backed step labels its deterministic fallback with fallback and fallbackReason, so callers can tell a model result from a fallback one. Registry not-found is reported as a likely-unregistered signal, not a purchase guarantee, and trademark output is preliminary research only. Calls are metered against Naming Credits, and the account usage endpoint reports the remaining balance.

## For AI agents

Compile a naming brief, generate 4-50 product name candidates, check them across up to 5 TLDs and namespaces, rank 2-30 survivors, and research up to 3 finalists.

## Scope

Does not register domains, file trademarks, or give legal clearance. Use for generating, checking, ranking, and researching product names only.

## Capabilities

- Compile a naming brief from pasted text, a public HTTPS URL, or a public GitHub repository
- Generate 4-50 name candidates per batch with optional primary-domain checks and an excludedNames list from earlier rounds
- Check 1-100 names across up to 5 TLDs and namespaces, capped at 150 name and TLD combinations per call
- Rank 2-30 domain survivors with an independent model, falling back to the deterministic score order
- Research one to three finalists for namespaces, namesake evidence, risk signals, and manual verification links
- Read the account's Naming Credit balance and recent activity

## Use cases

### Agent-run naming sprint through Jentic

A developer asks their coding agent, connected through Jentic, to name a new open-source project. The agent compiles a brief from the repository URL, generates 24 candidates with checkPrimaryDomain on, ranks the survivors, and researches the top three. Passing the same X-Name-Ledger-Sprint value on the generation, ranking, and research calls keeps them under one shared provider-cost budget.

Example prompt: Call POST `/api/v1/brief` with url='https://github.com/example/project', pass the returned brief to POST `/api/v1/generate` with count=24 and tlds=['com','dev'], then send the survivors to POST `/api/v1/rank`

### Bulk domain and namespace checks

When a team already has a list of name ideas, the check operation scores them for domain and namespace availability in one call. It accepts 1-100 names and up to 5 TLDs, with names times TLDs capped at 150. Oversized namespace work degrades explicitly to unknown through boundedDegradation instead of failing the request.

Example prompt: Call POST `/api/v1/check` with names=['ledgerly','tallyfox','quillpath'], tlds=['com','io','dev'], and includeNamespaces=true, then list the names with a likely-unregistered .com

### Finalist research before committing

Before adopting a name, a founder wants to know what else shares it. The research operation takes one to three finalists and returns namespaces, source-backed namesake evidence when the search provider is configured, risk signals, and links for manual checks. Trademark output is preliminary research, so the agent flags the manual verification steps instead of treating the result as clearance.

Example prompt: Call POST `/api/v1/research` with names=['tallyfox'] and tlds=['com','io'], then summarise the risk signals and list the manual verification links

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/brief` | Compile a naming brief |
| POST | `/api/v1/generate` | Generate name candidates |
| POST | `/api/v1/check` | Check and score names across TLDs |
| POST | `/api/v1/rank` | Rank domain survivors |
| POST | `/api/v1/research` | Research finalists |
| GET | `/api/v1/account/usage` | Read credit balance and activity |

## Key resources

- **Brief** — An editable naming brief compiled from text or a public URL
- **Candidates** — Generated name candidates with optional primary-domain results
- **Checks** — Domain and namespace availability scores per name and TLD
- **Research** — Finalist namesake evidence, risk signals, and manual verification links
- **Account usage** — Naming Credit balance and recent activity for the caller

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 66 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/namingsignal.com/namingsignal/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring NamingSignal by hand means creating a user API key, sending Idempotency-Key and X-Name-Ledger-Sprint headers so retries do not re-charge credits, and reading fallback labels and Retry-After on rate-limited responses. Through Jentic you install once, import NamingSignal from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** NamingSignal carries names and briefs in the request body, so rules bound which operations your agent may call, not which names it sends. Limit the agent to the operations it needs, such as checking names, and leave the credit-heavy generation and research operations out unless you add them.
- **Credential handling:** Your NamingSignal API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate product name ideas' or 'check domain availability for names', and Jentic returns the matching NamingSignal operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GoDaddy Domains API (OTE)** — Domain availability, purchase, and DNS management in GoDaddy's test environment
- **IP2WHOIS API** — WHOIS lookup for registrar, registrant, and expiry of a domain

## FAQ

### What authentication does the NamingSignal API use?

Per its OpenAPI spec, the NamingSignal API uses a bearer token: a user-owned API key created after sign-in at the NamingSignal developers page, sent as Authorization: Bearer. GET `/api/v1/health` is public and needs no credential. Revoked or expired keys return 401. Through Jentic, the key is stored once by your own Jentic One instance and injected at call time.

### How are NamingSignal API calls metered?

Calls draw on Naming Credits. Generation costs one generation unit plus one domain_check unit per candidate when checkPrimaryDomain is true, check costs one domain_check unit per name and TLD combination, rank costs one ranking unit, and research costs one research unit per finalist. Send an Idempotency-Key so a retried request replays the stored response instead of charging again.

### What are the rate limits for the NamingSignal API?

The spec says rate-limited responses carry Retry-After, retryAfterSeconds, and resetAt, and that GET `/api/v1/health` reports the applied limits, including the Naming Credit schedule. It does not list fixed numbers in the spec itself, so read the health endpoint for the current values.

### Is there a NamingSignal MCP server?

Yes. NamingSignal exposes a remote MCP endpoint at POST /mcp that uses the same API key. You can also connect the NamingSignal API directly through Jentic: your agent gets the full 8-endpoint surface without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I run a naming sprint through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the NamingSignal API from the API Directory, and store your API key once. Your agent searches for 'generate product name ideas', gets compileBrief and generateCandidates with their input schemas, and chains them with checkNames and rankDomainSurvivors. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the NamingSignal API?

Yes. To cap credit spend, write a rule that allows only checkNames and getAccountUsage, so the agent can score names you already have and watch the balance but cannot start model generation, ranking, or research runs. Add generateCandidates when you want it to propose names too.