Developer API · v1.0.0

yournewhandle API

Paid programmatic access to the full phonetic generator, batch username checks across 354 platforms, and AI handle suggestions — the same engine that powers the web studio.

Base URL: https://yournewhandle.com/api/v1

Overview

Programmatic access to yournewhandle generation and username availability checks across social platforms.

JSON REST API under /api/v1
Bearer token authentication for paid endpoints
Rate limits by plan with standard response headers
Platform checks use the same NickCheckr-backed pipeline as the web app

Authentication

All paid endpoints require a Bearer API key in the Authorization header.

Include your API key on every authenticated request:

Authorization: Bearer ynh_live_your_secret_key

Subscribe via Stripe Checkout. Your API key appears on the success page after payment and is tied to your subscription.

Plans & limits

Subscribe via Stripe Checkout to receive your API key. Starter, Pro, and Enterprise tiers with per-minute and daily quotas.

Getting your API key

Choose a plan below and complete Stripe Checkout.
After payment, your key appears on the success page (starts with ynh_live_). Copy it immediately — it is shown once.
Send it on every request: Authorization: Bearer YOUR_API_KEY
Manage billing or cancel anytime via Manage billing at the bottom of this page (use the email from checkout).

Starter

$19/mo

Light checks on popular platforms, phonetic generation.

500 req/day
20 req/min
Batch: 3 handles × 50 platforms
Deep check: Light only
AI generate: No

Pro

$79/mo

Full platform catalog, batch checks, AI generation.

25,000 req/day
120 req/min
Batch: 20 handles × 400 platforms
Deep check: Yes
AI generate: Yes

Enterprise

$199/mo + usage

$199 monthly platform fee, then graduated per-request usage on your monthly invoice.

Platform fee: $199/mo
Usage (graduated, billed monthly):
First 500,000 requests/mo: $0 usage charge (covered by platform fee)
500,001 – 2,000,000 requests/mo: $2.00 per 1,000 requests ($0.002 each)
2,000,001+ requests/mo: $1.00 per 1,000 requests ($0.001 each)
API rate limits:
600 req/min · 500,000 req/day max
Batch: 100 handles × 400 platforms
Deep check: Yes
AI generate: Yes

Rate limits

Quota headers on every authenticated response.

Authenticated responses include quota headers:

X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 116
X-RateLimit-Limit-Day: 25000
X-RateLimit-Remaining-Day: 24818

When exceeded, the API returns 429 with Retry-After seconds.

Errors

Structured error payloads with machine-readable codes.

Code	HTTP	Description
unauthorized	401	Missing or invalid API key.
api_disabled	503	No API keys configured on this deployment.
rate_limit_exceeded	429	Minute or daily quota exhausted.
plan_forbidden	403	Feature not included in your plan.
invalid_request	400	Malformed JSON or validation failure.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the reset time.",
    "retryAfter": 60
  }
}

Endpoints

REST JSON API under /api/v1.

GET/api/v1Public

API info

Public metadata — version, platform count, documentation links.

Response

{
  "name": "yournewhandle API",
  "version": "1.0.0",
  "platformCount": 354,
  "documentation": "https://yournewhandle.com/developers",
  "authenticated": false
}

Example

curl -s https://yournewhandle.com/api/v1

GET/api/v1/accountAuth required

Account & usage

Returns your plan, label, and current rate-limit consumption.

Response

{
  "key": { "id": "ynh_live…abcd", "label": "Production", "plan": "pro" },
  "limits": {
    "requestsPerMinute": 120,
    "requestsPerDay": 25000,
    "maxBatchHandles": 20,
    "maxBatchPlatforms": 400,
    "allowDeepCheck": true,
    "allowAiGenerate": true,
    "maxGenerateBatch": 48
  },
  "usage": {
    "minuteUsed": 4,
    "dayUsed": 182,
    "tracking": "redis"
  }
}

Example

curl -s https://yournewhandle.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/platformsAuth required

List platforms

Returns all 354 wired platforms with ids, categories, and nick-checkr service names.

Response

{
  "count": 354,
  "platforms": [
    {
      "id": "instagram",
      "name": "Instagram",
      "category": "Popular",
      "service": "Instagram",
      "wired": true,
      "minLength": 1,
      "maxLength": 30
    }
  ]
}

Example

curl -s https://yournewhandle.com/api/v1/platforms \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/generateAuth required

Generate handles

Phonetic and dictionary engine — same parameters as the web studio matrix.

Request body

{
  "minLen": 4,
  "maxLen": 12,
  "batchSize": 12,
  "dictionaryWeight": 85,
  "compound": true,
  "mode": "phonetic",
  "seed": "optional-reproducible-seed"
}

Response

{
  "count": 12,
  "handles": [
    { "handle": "velocraft", "normalized": "velocraft", "mode": "phonetic" }
  ]
}

Example

curl -s -X POST https://yournewhandle.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minLen":4,"maxLen":10,"batchSize":6,"compound":true}'

Accepts any GenerationParams field from the web app (languageWeights, blueprint, affixTier, etc.).
batchSize is capped by your plan's maxGenerateBatch.

POST/api/v1/checkAuth required

Check one platform

Check username availability on a single platform by service name or platform id.

Request body

{
  "handle": "velocraft",
  "platformId": "instagram"
}

Response

{
  "handle": "velocraft",
  "platformId": "instagram",
  "service": "Instagram",
  "status": "available",
  "message": "Username available",
  "profileUrl": "https://instagram.com/velocraft",
  "cached": false
}

Example

curl -s -X POST https://yournewhandle.com/api/v1/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"velocraft","platformId":"instagram"}'

Use platformId from GET /platforms, or pass service directly (NickCheckr service name).
status is one of: available, taken, unknown, error.

POST/api/v1/check/batchAuth required

Batch check

Check multiple handles across many platforms in one request.

Request body

{
  "handles": ["velocraft", "neonforge"],
  "mode": "light",
  "platformIds": ["instagram", "github", "tiktok"]
}

Response

{
  "mode": "light",
  "handleCount": 2,
  "platformCount": 3,
  "results": [
    {
      "handle": "velocraft",
      "platformId": "instagram",
      "status": "available",
      "message": "Username available"
    }
  ]
}

Example

curl -s -X POST https://yournewhandle.com/api/v1/check/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handles":["velocraft"],"mode":"light"}'

mode: light (top 50 popular) or deep (full catalog). Deep requires Pro or Enterprise.
Omit platformIds to check all platforms in the selected mode.

POST/api/v1/ai/generateAuth required

AI generate

Natural-language handle suggestions powered by Gemini with engine fallback.

Request body

{
  "prompt": "short futuristic creator handle, easy to say",
  "referenceHandle": "velocraft",
  "count": 8,
  "minLen": 4,
  "maxLen": 14
}

Response

{
  "count": 8,
  "suggestions": ["novastream", "pulseforge"],
  "source": "gemini"
}

Example

curl -s -X POST https://yournewhandle.com/api/v1/ai/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"futuristic gaming handle","count":6,"minLen":4,"maxLen":12}'

Requires Pro or Enterprise plan.
source is gemini or engine when AI output is empty.

Manage billing

Update your card, view invoices, or cancel your subscription in the Stripe customer portal.

Contact

Questions about the API, billing, or enterprise plans? Reach out — we typically reply within one business day.

hello@yournewhandle.com — general inquiries
support@yournewhandle.com — technical support & API access

Code

HTTP

Description

unauthorized

401

Missing or invalid API key.

api_disabled

503

No API keys configured on this deployment.

rate_limit_exceeded

429

Minute or daily quota exhausted.

plan_forbidden

403

Feature not included in your plan.

invalid_request

400

Malformed JSON or validation failure.

{ "key": { "id": "ynh_live…abcd", "label": "Production", "plan": "pro" }, "limits": { "requestsPerMinute": 120, "requestsPerDay": 25000, "maxBatchHandles": 20, "maxBatchPlatforms": 400, "allowDeepCheck": true, "allowAiGenerate": true, "maxGenerateBatch": 48 }, "usage": { "minuteUsed": 4, "dayUsed": 182, "tracking": "redis" } }

{ "count": 354, "platforms": [ { "id": "instagram", "name": "Instagram", "category": "Popular", "service": "Instagram", "wired": true, "minLength": 1, "maxLength": 30 } ] }

curl -s -X POST https://yournewhandle.com/api/v1/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"minLen":4,"maxLen":10,"batchSize":6,"compound":true}'

{ "handle": "velocraft", "platformId": "instagram", "service": "Instagram", "status": "available", "message": "Username available", "profileUrl": "https://instagram.com/velocraft", "cached": false }

{ "mode": "light", "handleCount": 2, "platformCount": 3, "results": [ { "handle": "velocraft", "platformId": "instagram", "status": "available", "message": "Username available" } ] }

curl -s -X POST https://yournewhandle.com/api/v1/ai/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"futuristic gaming handle","count":6,"minLen":4,"maxLen":12}'