A practical cookbook for asking AI agents — Claude Code in particular — to do useful work against your NetSuite account through Chartstone’s local API.
You can point any tool at any HTTP API. The reason Chartstone is uniquely good for AI agents is what the architecture removes:
/records-catalog and
/records-catalog/schema let an agent ask
“what record types exist” and “what fields
does X have” without you pre-registering tools per
record. The agent can navigate your data model from a single
prompt.
Accept: application/toon on any JSON
endpoint and Chartstone returns the response in TOON — a
compact, header-once format that’s 25–50% cheaper
to feed back into an LLM than equivalent JSON. Big result
sets stay affordable.
127.0.0.1, so an agent
running on your machine can reach NetSuite without anyone
authorizing a remote tool, opening firewall holes, or
forwarding credentials off-machine.
/script lets an agent run arbitrary SuiteScript
against your session — useful for quick debugging, one-off
transforms, or scenarios SuiteQL can’t express. Off by
default; opt in per-install when you trust the agent.
Claude Code is a CLI agent that runs on your machine and uses plain HTTP and shell tools — exactly what Chartstone needs. Setup takes about 30 seconds:
1. Start the Chartstone server
Open Chartstone, sign in to NetSuite, click Start server in the Local HTTP server card. Note the port and shared secret shown there.
2. Tell Claude Code where to call
Drop something like this into your prompt or
CLAUDE.md file at the project root. Replace the
two placeholders with the values shown in the Chartstone
control panel.
## Chartstone (local NetSuite API)
Chartstone is running locally on port <YOUR-PORT> with shared secret
<YOUR-SECRET>. Both values are visible in the Chartstone control
panel under "Local HTTP server."
To call any endpoint:
curl -sS http://127.0.0.1:<YOUR-PORT>/<endpoint> \
-H "Authorization: Bearer <YOUR-SECRET>" \
-H "Content-Type: application/json" \
-d '<json body>'
Always call /health FIRST. Its response body lists the endpoints that
are currently enabled (and which are disabled), so you know what's
reachable before you build a query. Its response headers include the
current tier limits and usage:
X-MaxQueries / X-QueriesRun (e.g. /suiteql)
X-MaxReports / X-ReportsRun (e.g. /search, /report)
X-MaxScripts / X-ScriptsRun (e.g. /script, /restlet)
Max values of 999999 mean unlimited (Pro tier). Smaller maxes (30 / 15
/ 15) mean Lite tier — budget your calls and prefer "maxRows" on
/suiteql plus "Accept: application/toon" on big result sets.
Send "Accept: application/toon" on any JSON endpoint to get
token-optimized output instead of JSON (~25–50% fewer tokens).
Full API reference: https://chartstone.io/api/
3. Ask
That’s it. The agent calls /health on its
first turn to discover what’s reachable and what the
per-launch budget looks like, then answers questions, builds
queries, and produces reports from there.
Cursor uses the same approach. Add the same block to either
Cursor Settings → Rules for AI (project-level)
or to a project-root .cursorrules file:
# .cursorrules
## Chartstone (local NetSuite API)
Chartstone is running locally on port <YOUR-PORT> with shared secret
<YOUR-SECRET>. Both values are visible in the Chartstone control
panel under "Local HTTP server."
Always call /health FIRST. Body lists enabled endpoints; headers
(X-MaxQueries / X-QueriesRun, etc.) reveal the per-launch budget so
you know whether to splurge or conserve.
For requests:
curl -sS http://127.0.0.1:<YOUR-PORT>/<endpoint> \
-H "Authorization: Bearer <YOUR-SECRET>" \
-H "Content-Type: application/json" \
-d '<json body>'
Send "Accept: application/toon" on JSON endpoints to save tokens
(~25–50% cheaper to feed back to me).
Full API reference: https://chartstone.io/api/
Continue lets you register external commands as tool wrappers.
Drop the API surface into Continue’s
system message (Settings → Configure System
Message) — same content as the Claude Code block above. Then,
if you want one-key tool invocations, add a custom command to
~/.continue/config.json:
{
"customCommands": [
{
"name": "ns",
"description": "Call a Chartstone endpoint",
"prompt": "Use the Chartstone local API at port <YOUR-PORT> with bearer secret <YOUR-SECRET> to: {{{ input }}}. Always start by calling /health to discover the endpoint surface and check usage headers."
}
]
}
Then in chat: /ns find the top 10 customers by YTD
revenue. Continue rewrites the request, picks the right
endpoint, and calls Chartstone for you.
Any tool that can issue HTTP requests from your machine works
the same way: tell it the port and secret, point at
/health first, then iterate. We’ve seen good
results with custom agent frameworks (LangChain, Mastra, custom
OpenAI-API loops), Aider, and ChatGPT desktop’s custom
tools.
A growing collection of prompts that exercise each part of the API. Copy any of these into Claude Code (or your agent of choice) and adjust the specifics for your account.
/suiteql
Top customers
“Find the top 25 customers by year-to-date sales. Show their entityid, company name, and total revenue.”
What the agent does
Writes a SuiteQL SELECT … FROM customer JOIN
transaction … with a SUM(amount)
aggregate, posts to /suiteql, formats the
response.
Stale items
“Which inventory items haven’t sold in 12 months? I want SKU, description, and last-sold date.”
What the agent does
Joins item against transaction /
transactionLine, uses MAX(date)
and a 12-month filter, returns the result.
Anomaly hunt
“Find any sales orders this month with a total over $50K that don’t have a credit-card-on-file. Show the order number, customer, amount, and creator.”
What the agent does
Composes the query, runs it, returns formatted results. If
the agent isn’t sure about a field name, it asks
/records-catalog/schema first.
systemNote
Who changed what, when
“Who changed any customer’s credit limit in the last 90 days? Show the customer, the user, the old value, the new value, and the timestamp.”
What the agent does
Queries systemNote filtered to
recordtypeid = customer and
field = creditlimit over the date range; joins
against the customer record for company name; returns the
audit trail.
Compliance digest
“Build me a weekly digest of every change to GL account records — who, what field, before/after — so I can email it to our controller.”
What the agent does
Queries the matching systemNote rows, formats
them as markdown grouped by user, hands you the result. You
can pipe that into your mail client.
/records-catalog
Field reference
“What fields does the salesorder record have? Mark which ones are required.”
What the agent does
Calls /records-catalog/schema for salesorder
and renders a clean field list. Useful before building any
query that touches the record.
Custom-record discovery
“What custom records exist in this account? Which ones have a Status field?”
What the agent does
Walks /records-catalog, filters to custom
record types, then calls
/records-catalog/schema for each to look for
the field. Returns a tidy list.
/reports + /report
Run with overrides
“Run the A/R Aging Summary report for last quarter and flag any customer over 90 days.”
What the agent does
/reports to find the right report ID,
/report-info to find the period filter,
/report with the period override, then filters
the response rows to overdue customers.
Cross-report comparison
“Compare the Income Statement for this quarter to the same quarter last year. What categories moved most?”
What the agent does
Runs the report twice with different period filters, diffs the rows, sorts by absolute change, narrates the findings.
/page
Scrape what SuiteQL can’t reach
“Pull the dashboard from SuiteAnalytics and summarize the top alerts.”
What the agent does
Calls /page with mode: "markdown"
against the dashboard URL, summarizes the result. Useful for
account areas that aren’t addressable through SuiteQL
or saved searches.
/script
opt-in
Quick runtime check
“Tell me what role I’m logged in as right now, and which subsidiary it’s scoped to.”
What the agent does
Sends a short SuiteScript snippet
(require('N/runtime').getCurrentUser()) to
/script, returns the result. Faster than going
through SuiteQL when the answer is “just inspect the
session.”
/script can run arbitrary code in your NetSuite
session, so it’s disabled by default. Enable it under
Local HTTP server → Endpoints →
Manage when you trust the agent and the
context.
<account>.app.netsuite.com in URL fields;
naming your account up front saves a back-and-forth.
Accept: application/toon. Same data, smaller
context, lower cost per turn.
maxRows for sampling. When
you only need a feel for a result set, ask the agent to add
"maxRows": 50 to its /suiteql body.
Drops the round-trip cost a lot.
/restlet and
/script off by default. Both can
mutate or execute. Enable per-install only after you’ve
decided you trust the agent and the context.
Once an agent is comfortable with read-only work, the Chartstone Toolkit is the next step. It’s a companion RESTlet (one file, you install it once) that gives agents the rest of the SuiteScript dev surface — file-cabinet ops, role and permission management, custom records / fields / lists / segments, and generic record CRUD — through 29 functions behind one discoverable endpoint.
The toolkit closes the gap that /script can’t
reach: NetSuite’s validator and formatter functions
aren’t available in the ad-hoc script context, so creating
a custom field with a TEXT, DATE, or
CURRENCY type — or assigning role permissions, or
creating custom record types — fails from /script
but works cleanly through the Toolkit.