Utility Execution API

Run a single utility transformation without building a pipeline.

Endpoint: POST /api/v1/utilities/{utilityId} Required permission: utilities

Request


curl -X POST https://forgejson.com/api/v1/utilities/schema.clean-json \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "primary": {
        "name": "Alice",
        "email": null,
        "tags": [],
        "bio": ""
      }
    },
    "config": {
      "removeNulls": true,
      "removeEmptyStrings": true,
      "removeEmptyArrays": true
    }
  }'

Request body


{
  "inputs": {
    "primary": <any JSON value>,
    "secondary": <any JSON value>
  },
  "config": { <utility-specific settings> }
}

Field	Type	Required	Description
`inputs.primary`	any JSON	Yes	The primary input passed to the utility
`inputs.secondary`	any JSON	No	Secondary input for multi-input utilities such as deep merge
`config`	object	No	Utility configuration (merged with defaults)

If config is omitted, the utility runs with its default settings.

Response (200) — Success


{
  "success": true,
  "output": {
    "name": "Alice"
  },
  "durationMs": 3,
  "creditsUsed": 1
}

Field	Type	Description
`output`	any JSON	The transformed result
`durationMs`	number	Execution time in milliseconds
`creditsUsed`	number	Credits consumed (1 per successful run)

Available utility IDs

ID	Name	Category
`convert.csv-to-json`	CSV to JSON	convert
`convert.json-to-csv`	JSON to CSV	convert
`convert.add-localization`	Add Localization	localization
`structure.find-replace`	Find & Replace	convert
`merge.deep-merge`	Deep Merge	merge
`structure.flatten-nest`	Flatten / Nest	structure
`structure.restructure`	Restructure	structure
`structure.pick-fields`	Pick Fields	structure
`structure.remove-fields`	Remove Fields	structure
`structure.copy-move`	Copy / Move	structure
`schema.normalize`	Normalize	schema
`schema.clean-json`	Clean JSON	cleanup
`schema.truncate`	Truncate	schema
`schema.compute`	Compute Fields	schema
`analysis.aggregate`	Aggregate	analysis
`analysis.summarize`	Summarize	analysis
`analysis.diff`	Diff	analysis
`cleanup.format-values`	Format Values	cleanup
`cleanup.redact`	Redact	cleanup
`cleanup.map-values`	Map Values	cleanup
`generate.generate-mock-data`	Generate Mock Data	generate
`generate.filter`	Filter	generate

Browse the Store for interactive examples and full configuration options for each utility.

Common examples

Clean JSON

Remove nulls, empty strings, and trim whitespace:


curl -X POST https://forgejson.com/api/v1/utilities/schema.clean-json \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "primary": {"name": " Alice ", "email": null, "role": ""}
    },
    "config": {"removeNulls": true, "removeEmptyStrings": true, "trimStrings": true}
  }'

Output: {"name": "Alice"}

Find & Replace

Replace values across the entire document:


curl -X POST https://forgejson.com/api/v1/utilities/structure.find-replace \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "primary": {"greeting": "hello world", "message": "hello there"}
    },
    "config": {"search": "hello", "replacement": "hi", "mode": "value"}
  }'

Output: {"greeting": "hi world", "message": "hi there"}

Pick Fields

Keep only specific fields:


curl -X POST https://forgejson.com/api/v1/utilities/structure.pick-fields \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "primary": {"name": "Alice", "age": 25, "email": "a@b.com", "ssn": "123-45-6789"}
    },
    "config": {"paths": ["name", "email"]}
  }'

Output: {"name": "Alice", "email": "a@b.com"}

Redact sensitive data

Mask emails and phone numbers:


curl -X POST https://forgejson.com/api/v1/utilities/cleanup.redact \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "primary": {"email": "alice@example.com", "phone": "555-1234"}
    },
    "config": {"patterns": ["email", "phone"], "maskStyle": "partial"}
  }'

Output: {"email": "a***@example.com", "phone": "***-1234"}

Size limits

Limit	Value
Maximum payload size	50 MB
Worker threshold	Payloads > 2 KB run in a worker thread
Worker timeout	30 seconds

Error responses

Status	Meaning
`400`	Missing `inputs.primary`, invalid JSON, or utility execution failed
`404`	Utility not found
`401`	Authentication failed
`403`	Missing `utilities` permission
`408`	Execution timed out (30s for worker)
`413`	Payload exceeds 50 MB
`429`	Rate limit exceeded
`500`	Internal server error