Nominal Public API — v1

The Nominal Public API exposes the same JSON↔CSV conversion the web app runs, callable from curl, JavaScript, Python, or any HTTP client. Authentication is via API keys minted from your account's /settings page. The endpoint accepts up to 1 MB per request and returns the converted output as JSON.

Quickstart

Three steps to your first successful call:

1. Subscribe to Pro from /pricing — the Public API is a Pro-only feature.
2. Mint an API key from /settings by clicking Generate new key. Copy the raw token — the dashboard only shows the first 16 characters.
3. Call POST /api/v1/convert with the raw key as a Bearer token.

# 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":"[{\"a\":1},{\"a\":2}]","direction":"json_to_csv"}'

{
  "success": true,
  "direction": "json_to_csv",
  "output": "a\n1\n2\n",
  "bytes_in": 21,
  "bytes_out": 6
}

const res = await fetch(
  'https://nominal-vrkp.polsia.app/api/v1/convert',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input: '[{"a":1},{"a":2}]',
      direction: 'json_to_csv'
    })
  }
);
const json = await res.json();

{
  "success": true,
  "direction": "json_to_csv",
  "output": "a\n1\n2\n",
  "bytes_in": 21,
  "bytes_out": 6
}

import requests

r = requests.post(
    "https://nominal-vrkp.polsia.app/api/v1/convert",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={"input": '[{"a":1},{"a":2}]', "direction": "json_to_csv"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["output"])

{
  "success": true,
  "direction": "json_to_csv",
  "output": "a\n1\n2\n",
  "bytes_in": 21,
  "bytes_out": 6
}

Authentication

Every request must include an Authorization header of the form:

Authorization: Bearer nk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are sha256-hashed server-side; only the prefix and the hash live in our database. The raw key is shown exactly once at mint time — store it somewhere safe immediately. If you lose it, revoke the old key and mint a new one from /settings.

• Prefix: nk_ + 64 hex characters (total 67 chars).
• Dashboard display: only the first 16 characters (nk_ + 13 hex chars).
• Revocation: any time from /settings — immediate, no confirmation email.

POST /api/v1/convert

Convert a JSON array to CSV, or CSV back to a JSON array. The endpoint uses dot-notation flattening for nested objects and arrays are serialized as JSON strings within a single cell.

Code samples

Each tab is a real, copy-pasteable example. Replace <YOUR_API_KEY> with the raw key from /settings; replace the example payload with your own data.

# 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":"[{\"a\":1},{\"a\":2}]","direction":"json_to_csv"}'

# Convert a CSV back to JSON.
curl -sX POST https://nominal-vrkp.polsia.app/api/v1/convert \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"a,b\\n1,2\\n3,4\",\"direction\":\"csv_to_json\"}"

const API_KEY = '<YOUR_API_KEY>';
const BASE = 'https://nominal-vrkp.polsia.app';

async function convert(input, direction) {
  const res = await fetch(`${BASE}/api/v1/convert`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: '{"input":"[{\\"a\\":1},{\\"a\\":2}]","direction":"json_to_csv"}'
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error || 'convert failed');
  return json.output;
}

convert('[{"a":1},{"a":2}]', 'json_to_csv')
  .then(csv => console.log(csv));
  // 'a\n1\n2\n'

import json
import requests

API_KEY = "<YOUR_API_KEY>"
BASE = "https://nominal-vrkp.polsia.app"

def convert(text: str, direction: str) -> str:
    r = requests.post(
        f"{BASE}/api/v1/convert",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"input": text, "direction": direction},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["output"]

print(convert('[{"a":1},{"a":2}]', "json_to_csv"))
# 'a\n1\n2\n'

Rate limits

Pro subscribers have no daily cap on API usage. The 2/day limit enforced for free web usage does not apply to the Public API — your API key must belong to an active Pro subscription, and once it does, conversion counts share the same UTC-day window only for diagnostics.

The response headers advertise the current quota state so you can surface it in your own monitoring:

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

For free accounts, when an API key is somehow minted before the subscription is active, the endpoint returns 403 { "error": "pro_required" } — never a partial quota. There is no per-minute rate limit enforced in v1; abusive traffic should be raised with support@nominal.app.

Errors

All errors are returned with a JSON body of { "error": "<code>", ... }. Stable error codes so your retry logic can branch on them.