Reference

Catalog API

GET-only ecommerce catalog API on mcp.neonjelly.io. Same nj_ key as MCP.

Base: https://mcp.neonjelly.io

Same nj_ key works for MCP and the catalog REST. REST is GET-only (including signal reads + product-idea search). Create a watch via MCP create_signal. No scrape. No probe.

curl -H "Authorization: Bearer nj_…" "https://mcp.neonjelly.io/v1/whoami"
curl -H "Authorization: Bearer nj_…" "https://mcp.neonjelly.io/v1/stores?q=gruntstyle&limit=3"

Also X-Api-Key: nj_…. Do not put the key in a query string in production.

Live tester: /playground.

Catalog (auth)

Stores, apps, analytics, signals, product ideas: see tools. Products, idea search, and every change feed: products.

Blocked on REST: POST/PATCH/DELETE, /v1/scrapes, /v1/signals/{id}/probe. MCP create_signal is the exception.

Platform

Method	Path	Auth	Does
`GET`	`/` `/v1` `/health`	none	Service JSON
`POST`	`/v1/trial`	none	Mint or reuse trial. Body: `installId`, optional `client`
`GET`	`/v1/whoami`	`nj_` / `njc_`	Key + quotas (not metered)
`GET`	`/v1/upgrade`	none / `nj_`	Checkout URL (not metered). Works after trial expiry.
`GET`	`/admin/keys`	`ADMIN_TOKEN`	List keys
`POST`	`/admin/keys`	`ADMIN_TOKEN`	Mint
`PATCH`	`/admin/keys/:id`	`ADMIN_TOKEN`	Revoke / quotas
`POST/GET/DELETE`	`/mcp`	`nj_` / `njc_`	MCP
`POST/GET/DELETE`	`/c/:connectToken/mcp`	token in path	MCP

Trial response

{
  "existing": false,
  "key": {
    "id": "…",
    "prefix": "nj_…",
    "plan": "trial",
    "dailyQuota": 100,
    "rateLimitPerMin": 20
  },
  "connectUrl": "https://mcp.neonjelly.io/c/njc_…/mcp",
  "secret": "nj_…"
}

secret omitted when existing: true. Expired device+client → 403 { error: { code: "trial_used", checkout: "https://neonjelly.io/pricing" } }.

MCP errors

Tool failures come back as MCP text with this shape (from the catalog):

{
  "error": {
    "code": "not_found|bad_request|unauthorized|rate_limited|query_timeout|internal|upstream_error",
    "message": "…",
    "details": {}
  }
}

Lists:

{
  "data": [],
  "page": {
    "limit": 20,
    "offset": 0,
    "count": 0,
    "hasMore": false,
    "total": 0
  },
  "meta": {}
}

Neonjelly gate 401/429 (before MCP) uses the same error.code idea. 429 body includes retryAfter (seconds) or dailyQuota. We do not set Retry-After / X-RateLimit-* headers.