Introducing the Nominal Public API — JSON↔CSV Conversion as a Service

The Nominal Public API is live. If you've ever needed to convert JSON to CSV — or CSV back to JSON — from a script, a scheduled job, a webhook, or any HTTP client, you can now do it in one authenticated POST. No browser. No copy-paste from a UI. One endpoint, one Bearer token, and the same conversion logic the web app runs.

This post covers what shipped, who it's for, and how to make your first call in under a minute. For the complete reference — request body, response shape, status codes, and language samples — see the full API documentation.

What Shipped: POST /api/v1/convert

The v1 API exposes a single endpoint that does both conversions on the same call, gated on a single field (direction):

That last line is worth pausing on: a valid API key still requires an active Pro subscription behind it. If your key is valid but your account lapsed, the endpoint returns 403 {"error":"pro_required"} — never a partial quota. We don't believe in soft-banning.

Who It's For

The Public API is built for the cases where the web app is the wrong tool:

• Backend pipelines — nightly jobs, ETL, and one-off migrations that need to flatten JSON exports into CSV
• Webhooks — receive an upstream JSON payload, convert on the fly, drop a CSV into S3 / BigQuery / a database
• Internal tools — long-running curls from a CLI; CI scripts that ship a CSV diff; an in-house admin tool that needs friction-free data conversion
• Replacing a flaky in-house parser — most edge cases around nested JSON flattening are already handled; see the deep dive on nested JSON → CSV for why that matters

Authentication and Key Issuance

Every request must carry an Authorization: Bearer header holding an API key. Keys are minted from your account's dashboard and prefixed nk_. We store their sha256 hash — the raw token is shown exactly once at mint time. The dashboard only displays the first 16 characters after that.

• Subscribe to Pro from /pricing (the Public API is Pro-only)
• Mint a key from the /dashboard API key tab — coming online this week alongside the launch
• Store the raw token in your secret manager immediately — it will not be shown again
• Revoke instantly from the same dashboard tab if a key leaks — no confirmation email, no grace period

Quickstart: One Code Block, One Minute

Replace <YOUR_API_KEY> with the raw token from the dashboard, then run:

# Convert a JSON array to CSV.
curl -sX POST https://nominal-vrkp.polsia.app/api/v1/convert \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"input":"[{\"name\":\"Ada\",\"city\":\"London\"},{\"name\":\"Bo\",\"city\":\"NYC\"}]","direction":"json_to_csv"}'
# → {"output":"name,city\nAda,London\nBo,NYC\n","direction":"json_to_csv","bytes_in":74,"bytes_out":34}

# And the reverse — parse CSV back to a JSON array.
curl -sX POST https://nominal-vrkp.polsia.app/api/v1/convert \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"input":"name,city\nAda,London","direction":"csv_to_json"}'
# → {"output":"[{\"name\":\"Ada\",\"city\":\"London\"}]","direction":"csv_to_json","bytes_in":17,"bytes_out":33}

JavaScript and Python equivalents — plus request/response schemas and every error code — live in the full API reference.

Rate Limits

Pro subscribers face no daily cap on the API. The 2/day limit you see on the free web app does not apply here — your API key unlocks unlimited calls as long as the subscription behind it stays active.

Every successful response advertises the quota state for your own monitoring:

X-Conversions-Used: 0
X-Conversions-Limit: unlimited

Per-minute throttling is intentionally out of scope for v1 — abusive traffic should be raised with support@nominal.app and we'll handle it directly. The 1 MB per-request ceiling is the only hard backstop a client will ever hit, and the endpoint returns a clean 413 {"error":"payload_too_large"} when it does.

What Changes for Free Users

Nothing. The free web app stays free. The 2-conversion-per-day limit on the unauthenticated converter is unchanged. API keys are a Pro feature, full stop — if you don't need them, nothing here costs you anything.

Read the Full Reference

This post is the why. The /developers page is the how. It documents the full request body, response shape, every documented status code, and copy-pasteable samples in curl, JavaScript (fetch), and Python (requests). Bookmark it — it's the canonical source of truth for the v1 API and will update as we ship new endpoints.

What's Next

v1 is the floor. We're already drafting v2 around three ideas: a /api/v1/batch endpoint for jobs that exceed the 1 MB single-call limit, structured output formats (ndjson, gzip on the wire), and a streaming variant for very large conversions. If something on that list would unblock you sooner, let us know — early feedback shapes what ships first.

Questions, edge cases, or just a working curl to share? support@nominal.app — we read everything.