POST JSON Extractor API
/api/v1/ai/json-extractor
Extract structured JSON objects from unstructured raw text based on a custom schema.
Architecture Role & AI Definition
JSON Extractor API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
text |
string | Required | The raw unstructured text containing data to be extracted (Max: 20,000 characters). |
schema |
object | Optional | Optional JSON object defining the key-value schema structure to guide the extraction. |
custom_instructions |
string | Optional | Optional text describing custom formatting, filtering, or sanitization rules (Max: 1,000 characters). |
allow_large_text |
boolean | Optional | Optional flag. Set to true to raise the maximum text size limit to 100,000 characters (charges 1 extra credit per 10k characters above 20k). |
Important Note on Credit Usage
The standard request limit is 20,000 characters (costs 3 base credits). If you need to process larger texts (up to 100,000 characters), you must explicitly set "allow_large_text": true in the request payload. Each additional 10,000 characters above the 20,000 threshold will consume 1 extra credit.
Example Request
{
"text": "The patient John Doe is 34 years old and has been diagnosed with mild flu. He was admitted on 2026-06-15.",
"schema": {
"patient_name": "string",
"patient_age": "integer",
"diagnosis": "string",
"admission_date": "string"
},
"custom_instructions": "Capitalize the diagnosis and format the date as YYYY-MM-DD."
}curl -X POST https://rsflowhub.com/api/v1/ai/json-extractor \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "The patient John Doe is 34 years old and has been diagnosed with mild flu. He was admitted on 2026-06-15.",
"schema": {
"patient_name": "string",
"patient_age": "integer",
"diagnosis": "string",
"admission_date": "string"
},
"custom_instructions": "Capitalize the diagnosis and format the date as YYYY-MM-DD."
}'Example Response
{
"success": true,
"data": {
"result": {
"extracted_data": {
"patient_name": "John Doe",
"patient_age": 34,
"diagnosis": "MILD FLU",
"admission_date": "2026-06-15"
},
"schema_conforms": true,
"parsed": true,
"raw_content": "{\n \"patient_name\": \"John Doe\",\n \"patient_age\": 34,\n \"diagnosis\": \"MILD FLU\",\n \"admission_date\": \"2026-06-15\"\n}"
}
},
"meta": {
"credits_used": 3,
"credits_remaining": 997
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/json-extractor' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"text": "The patient John Doe is 34 years old and has been diagnosed with mild flu. He was admitted on 2026-06-15.",
"schema": {
"patient_name": "string",
"patient_age": "integer",
"diagnosis": "string",
"admission_date": "string"
},
"custom_instructions": "Capitalize the diagnosis and format the date as YYYY-MM-DD."
}'Always provide a
schema parameter to guide the model. It ensures the response conforms exactly to your backend data models.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (2 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |