Use the JSO AI API when preset guidance, compatibility checks, error explanations, or usage data need to be part of an internal tool or CI workflow. Most users should start with AI settings, AI usage, or the browser previews before calling the API directly.
Common response shape
Successful responses return ok: true, a result object, and the provider that produced the answer.
{
"ok": true,
"previewMode": false,
"provider": "claude-byo",
"tokensIn": 420,
"tokensOut": 180,
"suggestion": { }
}
When no live provider key is available, previewMode is usually true and provider is rule-based. Account-level provider keys report openai-byo or claude-byo. Site-managed provider calls may report openai or claude when managed AI is enabled.
The outer envelope stays stable across preview and provider-backed mode. Preview result objects may include nested previewMode and source hints; provider-backed result objects should be validated by their business fields such as config / signals, summary / findings, or cause / fix.
Error responses return a stable error code and a human-readable message.
{
"ok": false,
"error": "input_invalid",
"message": "description is required"
}
POST /v1/ai/preset-suggest.ashx
Describe the project and get a starter protection profile.
curl -fsS -X POST https://javascriptobfuscator.com/v1/ai/preset-suggest.ashx \
-H "Content-Type: application/json" \
-d "{
\"APIKey\": \"$JSO_API_KEY\",
\"APIPwd\": \"$JSO_API_PASSWORD\",
\"description\": \"React SaaS frontend, balanced performance, lock to example.com\"
}"
The response includes a suggested config and the signals JSO AI used when choosing it.
POST /v1/ai/compat-check.ashx
Review JavaScript for patterns that may need attention before protection, such as dynamic code execution, framework reflection, public callbacks, or source-map leakage.
{
"APIKey": "$JSO_API_KEY",
"APIPwd": "$JSO_API_PASSWORD",
"source": "function pay(amt) { eval('api.charge(' + amt + ')'); }",
"framework": "react"
}
The response includes severity-graded findings with suggested fixes. For CLI users, jso-protector --ai-precheck is usually easier than calling this endpoint by hand.
POST /v1/ai/explain-error.ashx
Paste a protected-output runtime error and get the likely protection setting involved.
{
"APIKey": "$JSO_API_KEY",
"APIPwd": "$JSO_API_PASSWORD",
"error": "Uncaught TypeError: someMethod is not a function",
"config": "{ optional jso.config.json snippet }"
}
The response includes a likely cause, confidence level, practical fix, and docs link.
POST /v1/ai/usage.ashx
Return current-month AI usage for the account. This endpoint is free to poll and is the right source for dashboards or alerts.
{
"APIKey": "$JSO_API_KEY",
"APIPwd": "$JSO_API_PASSWORD"
}
The response includes tier, billing month, guided checks used, guided checks remaining, review capacity, approximate cost counters, quota rejections, source-free provider-key health, and timestamp.
{
"ok": true,
"previewMode": false,
"tier": "Basic",
"billingMonth": "2026-06-01",
"actionsUsed": 12,
"actionsCap": 50,
"actionsRemaining": 38,
"tokensUsed": 12000,
"tokensCap": 200000,
"tokensRemaining": 188000,
"approxCostCents": 320,
"costCapCents": 5000,
"costRemainingCents": 4680,
"quotaRejections": 0,
"providerKey": {
"hasKey": true,
"provider": "openai",
"status": "ready",
"label": "Key ready",
"testDue": false,
"rotationDue": false,
"lastTestStatus": "passed",
"lastTestUtc": "2026-06-08T12:00:00Z",
"nextTestDueUtc": "2026-07-08T12:00:00Z",
"rotationDueUtc": "2026-09-06T12:00:00Z",
"recommendedAction": "No action needed today."
},
"asOfUtc": "2026-06-08T12:01:00Z"
}
The providerKey object intentionally omits the provider secret and key suffix. Use status, testDue, rotationDue, and recommendedAction for monitoring alerts. The dashboard uses the same 30-day stored-key test and 90-day provider-access review cadence.
POST /v1/ai/checkout-create.ashx
Create a Stripe Checkout session for a managed AI plan only when managed AI billing is enabled. BYO-key accounts do not need checkout; save the provider key in AI settings.
{
"APIKey": "$JSO_API_KEY",
"APIPwd": "$JSO_API_PASSWORD",
"tier": "Basic",
"returnUrl": "https://javascriptobfuscator.com/dashboard/AIUsage.aspx"
}
Important error codes: managed_billing_disabled, checkout_not_configured, auth_failed, input_invalid, upstream_error, and internal_error.
POST /v1/ai/portal-create.ashx
Create a Stripe Customer Portal session for managed AI subscriptions. Manually activated or BYO-key-only accounts may not have a Stripe Customer ID, so the dashboard should fall back to support copy when the portal is unavailable.
Important error codes: portal_not_configured, stripe_customer_missing, auth_failed, upstream_error, and internal_error.
POST /v1/ai/stripe-webhook.ashx
Stripe calls this endpoint. Customers do not call it directly. It is documented here so integrators understand why managed subscriptions may update shortly after checkout completes.
Limits
Every successful guided action counts against the account's monthly JSO AI limit. BYO-key calls still count against JSO AI usage limits, while model charges go to the OpenAI or Claude account that owns the provider key. When a cap is reached, JSO AI returns quota_exhausted instead of billing surprise overages.
Client examples
Copy-paste starting points in curl, Python, Node, Go, .NET, Java, Ruby, PHP, Rust, and Kotlin are in AI client examples. Deployment and managed-billing notes are in AI deployment notes.
Frequently asked questions
What credentials does the AI API use?
The same key and password pair used for the protection API, sent in the request body alongside the endpoint's own fields. There is no separate credential to provision, which means an integration that already calls the protection API has everything it needs. The base path for these endpoints differs from the protection endpoint, so the change when adding them to an existing tool is the URL and the payload rather than the authentication.
What happens if we have not saved a provider key?
The call still succeeds and returns rule-based guidance rather than failing. Responses in that state report preview mode and identify the provider as rule-based, so an integration can detect the condition and decide whether to present the answer, label it, or prompt someone to configure a key. Designing for this from the start is worthwhile because it means a missing key degrades the feature rather than breaking the tool.
How do we tell which engine produced an answer?
From two fields in the envelope. A preview-mode indicator tells you whether the answer came from the rule-based path, and a provider field names what produced it. Account-level keys report a provider name suffixed to indicate they are your own, while site-managed calls report the plain provider name when managed AI is enabled. Together those two fields are enough to decide how much weight to give a response and how to label it in your own interface.
Which parts of the response are stable enough to depend on?
The outer envelope, which keeps the same shape across preview and provider-backed responses: a success flag, a result object, the provider, and token counts. Inside the result object the shape varies by endpoint, and preview results may carry extra nested hints that provider-backed results do not. The recommended approach is to validate provider-backed results by their business fields for the endpoint you called rather than by assuming a uniform structure across all of them.
How are errors reported?
As a structured response rather than only a status code. A failed call returns the success flag set to false, a stable machine-readable error code, and a human-readable message explaining what was wrong. Branch on the code and log the message; the code is the part designed to stay stable, and the message is the part designed to be read by a person looking at a build log.
Should we call these endpoints directly or use the dashboard?
Start with the dashboard and the browser previews, and move to the API when the guidance needs to live inside something else. The API earns its place when preset guidance, compatibility checking, error explanation or usage data has to be part of an internal tool or a continuous integration workflow, where a human opening a page is not an option. For exploratory use the browser surfaces are faster and require no integration work.
What do these endpoints receive from us?
It depends on the endpoint, and it is worth checking the one you intend to call rather than assuming they are alike. Some take only a written description of your project, while others are designed to examine code or an error. Because the answer differs per endpoint and matters for any assessment you have to complete, the processing boundary is documented separately and should be read before wiring a call into an automated pipeline.