Output formats

RolesAPI returns JSON by default, and can return CSV or NDJSON from results endpoints — useful for spreadsheets and stream processing without a conversion step on your side.

How do I choose a format?

Two ways, in order of precedence:

1. Query parameter — ?format=json|csv|ndjson. If present, it always wins.
2. Accept header — application/json, text/csv, or application/x-ndjson. Used only when format is absent.

# Query parameter (takes precedence)
curl "https://api.rolesapi.com/v1/jobs/job_01hxyz/results?format=csv" \
  -H "Authorization: Bearer rk_live_your_key"

# Accept header (used when ?format is absent)
curl "https://api.rolesapi.com/v1/jobs/job_01hxyz/results" \
  -H "Authorization: Bearer rk_live_your_key" \
  -H "Accept: text/csv"

If both are present and disagree, the query parameter is honored and the header is ignored.

How is JSON structured?

The standard envelope: data, meta on lists, request_id. See Quickstart and Pagination.

How does CSV flattening work?

CSV output contains only the rows — no envelope. Nested role objects flatten by three rules:

1. Nested objects become dot-path columns. company.name, salary.min, salary.currency.
2. Arrays are joined with |. benefits becomes Health insurance|401(k) matching|Paid time off.
3. Standard CSV quoting. Values containing commas, quotes, or newlines are wrapped in double quotes, with inner quotes doubled (RFC 4180).

The Acme Logistics role as a CSV row:

job_key,title,company.name,company.rating,location,remote,employment_type,salary.min,salary.max,salary.currency,salary.period,benefits,posted_at,country
a1b2c3d4e5f60718,Senior Backend Engineer,Acme Logistics,4.1,"Austin, TX",false,Full-time,140000,175000,USD,year,Health insurance|401(k) matching|Paid time off,2026-06-28,us

The header row is always present, and the column set is stable across rows of one response. Combine with field projection to control exactly which columns appear.

How does NDJSON work?

One JSON object per line, no envelope, no trailing commas — ideal for piping into stream processors or bulk-loading into a warehouse. Each line is one role:

curl -s "https://api.rolesapi.com/v1/jobs/job_01hxyz/results?format=ndjson" \
  -H "Authorization: Bearer rk_live_your_key" |
while IFS= read -r line; do
  echo "$line" | jq -r '[.job_key, .title, .company.name] | @tsv'
done

a1b2c3d4e5f60718  Senior Backend Engineer  Acme Logistics

Because NDJSON is line-delimited, you can begin processing the first role before the response finishes — no need to buffer the whole body as with a JSON array.

Where are formats available?

CSV and NDJSON apply to results-shaped endpoints, primarily GET /v1/jobs/{id}/results. Single-object endpoints such as GET /v1/roles/{job_key} and control-plane endpoints (/v1/jobs, /v1/webhooks, /v1/me) return JSON.