# Parsers & Generators

## List available flow processor types

> Returns the catalog of processor types the flow engine supports — filter,\
> transform, handlebars, javascript, mapper, CSV/XML parser / generator,\
> branch filter, merge, etc. Each entry carries a label, description, and\
> the input/output media types the processor accepts.\
> \
> Read-only catalog endpoint — safe to cache client-side for the session.\
> \
> AI guidance:\
> \- Response is \*\*keyed by processor name\*\* (not an array) — iterate\
>   \`Object.entries()\` or similar. Keys include: \`branchFilter\`, \`filter\`,\
>   \`transform\`, \`transformTwoDotZero\`, \`mapperProcessor\`, \`handlebars\`,\
>   \`javascript\`, \`csvParser\`, \`csvDataGenerator\`, \`xmlParser\`,\
>   \`structuredFileParser\`, \`structuredFileGenerator\`, \`merge\`,\
>   \`exportDataConverter\`.\
> \- Use the per-processor evaluate endpoints (\`POST /v1/processors/{name}\`)\
>   to test rules against sample data. \`POST /v1/processors/handlebars\` is\
>   the most common; it takes \`{rule, data}\` and returns the evaluated\
>   output.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ProcessorsResponse":{"type":"object","description":"Processor catalog keyed by processor name. Each value describes the\nprocessor's label, purpose, and input/output media types.","additionalProperties":{"$ref":"#/components/schemas/ProcessorDescriptor"}},"ProcessorDescriptor":{"type":"object","description":"Metadata describing a single processor type.","properties":{"name":{"type":"string","description":"Processor key (matches the enclosing object key)."},"label":{"type":"string","description":"Human-readable label shown in the UI."},"description":{"type":"string","description":"Short description of the processor's behavior."},"ruleMediaType":{"type":"string","description":"Media type of the processor's rule/template field. Typical values\ninclude `text`, `json`, `javascript`."},"dataMediaType":{"type":"string","description":"Media type the processor expects for the input data."},"resultMediaType":{"type":"string","description":"Media type the processor emits as its result."}},"required":["name","label"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors":{"get":{"operationId":"listProcessorTypes","tags":["Parsers & Generators"],"summary":"List available flow processor types","description":"Returns the catalog of processor types the flow engine supports — filter,\ntransform, handlebars, javascript, mapper, CSV/XML parser / generator,\nbranch filter, merge, etc. Each entry carries a label, description, and\nthe input/output media types the processor accepts.\n\nRead-only catalog endpoint — safe to cache client-side for the session.\n\nAI guidance:\n- Response is **keyed by processor name** (not an array) — iterate\n  `Object.entries()` or similar. Keys include: `branchFilter`, `filter`,\n  `transform`, `transformTwoDotZero`, `mapperProcessor`, `handlebars`,\n  `javascript`, `csvParser`, `csvDataGenerator`, `xmlParser`,\n  `structuredFileParser`, `structuredFileGenerator`, `merge`,\n  `exportDataConverter`.\n- Use the per-processor evaluate endpoints (`POST /v1/processors/{name}`)\n  to test rules against sample data. `POST /v1/processors/handlebars` is\n  the most common; it takes `{rule, data}` and returns the evaluated\n  output.","responses":{"200":{"description":"Processor catalog, keyed by processor name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessorsResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Convert XML to JSON

> Parses XML data into JSON records using the specified parsing rules\
> and resource path.\
> \
> \*\*Resource path format\*\* — Use XPath-style slash-separated paths\
> (e.g. \`/root/item\`). Dot-separated paths (e.g. \`root.item\`) do not\
> work.\
> \
> \*\*Legacy vs modern output\*\* — Without \`doc.parsers\` configured, or\
> with \`V0\_json: true\`, the parser produces a legacy format where\
> element text appears as \`\[{"\_": "value"}]\` arrays and attributes\
> appear under a \`$\` key. Setting \`V0\_json: false\` produces clean\
> key-value pairs and flattens attributes into the record.\
> \
> When \`groupByFields\` is used the response shape changes: \`data\`\
> becomes an array of arrays and \`dataRecordTraceKeys\` /\
> \`traceKeysDuplicate\` are omitted.\
> \
> Invalid XML does not return an error — it produces empty or\
> partial results. Namespaced XPath expressions (e.g. \`ns:element\`)\
> return an \`invalid\_xpath\` error.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ParserResponse":{"type":"object","description":"Response from a parser processor (`csvParser`, `xmlParser`).\n\nWhen `groupByFields` is used in the request, the `dataRecordTraceKeys`\nand `traceKeysDuplicate` fields are omitted from the response and `data`\nbecomes an array of arrays (each inner array is one group of records).","required":["mediaType","data","duration"],"properties":{"mediaType":{"type":"string","description":"Always `json` for parser processors.","enum":["json"]},"data":{"description":"Parsed records. Normally an array of objects. When `groupByFields`\nis used, becomes an array of arrays (grouped records).","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries). Omitted\nwhen `groupByFields` is used."},"traceKeysDuplicate":{"type":"boolean","description":"Whether any duplicate trace keys were detected. Omitted when\n`groupByFields` is used."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/xmlParser":{"post":{"operationId":"parseXml","tags":["Parsers & Generators"],"summary":"Convert XML to JSON","description":"Parses XML data into JSON records using the specified parsing rules\nand resource path.\n\n**Resource path format** — Use XPath-style slash-separated paths\n(e.g. `/root/item`). Dot-separated paths (e.g. `root.item`) do not\nwork.\n\n**Legacy vs modern output** — Without `doc.parsers` configured, or\nwith `V0_json: true`, the parser produces a legacy format where\nelement text appears as `[{\"_\": \"value\"}]` arrays and attributes\nappear under a `$` key. Setting `V0_json: false` produces clean\nkey-value pairs and flattens attributes into the record.\n\nWhen `groupByFields` is used the response shape changes: `data`\nbecomes an array of arrays and `dataRecordTraceKeys` /\n`traceKeysDuplicate` are omitted.\n\nInvalid XML does not return an error — it produces empty or\npartial results. Namespaced XPath expressions (e.g. `ns:element`)\nreturn an `invalid_xpath` error.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"The XML data to parse (as a string)."},"rules":{"type":"object","description":"Parsing rules. At minimum, provide `resourcePath` to select\nwhich XML elements become records. Add `doc.parsers` to\ncontrol the output format.","properties":{"resourcePath":{"type":"string","description":"Slash-separated path to the repeating element in the XML\n(e.g. `/root/items/item`). Each matching element becomes\none output record."},"groupByFields":{"type":"array","items":{"type":"string"},"description":"Group parsed records by these field names. Changes the\nresponse `data` to an array of arrays and omits\n`dataRecordTraceKeys` and `traceKeysDuplicate`."},"sortByFields":{"type":"array","items":{"type":"string"}},"doc":{"type":"object","properties":{"fileParser":{"type":"boolean"},"parsers":{"type":"array","description":"Array of parser configurations. Typically contains a\nsingle XML parser entry.","items":{"type":"object","properties":{"type":{"type":"string","enum":["xml"]},"version":{"type":"integer"},"rules":{"type":"object","properties":{"V0_json":{"type":"boolean","description":"When `false`, produces clean key-value output\nand flattens XML attributes into the record.\nWhen `true` (default), uses legacy format with\n`_` and `$` keys."},"trimSpaces":{"type":"boolean","description":"Trim leading/trailing whitespace from text nodes."},"stripNewLineChars":{"type":"boolean","description":"Remove newline characters from text nodes."}}}}}}}}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"Invalid XPath expression or processing rule error.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string"},"resolved":{"type":"boolean"},"occurredAt":{"type":"integer"},"path":{"type":"string"}}}}}}}}}}}
```

## Convert CSV to JSON

> Parses CSV data into JSON records using the specified delimiter and\
> formatting rules.\
> \
> Both \`data\` and \`rules\` are technically optional — omitting either\
> returns an empty result rather than an error. When \`hasHeaderRow\` is\
> false, columns are named \`Column0\`, \`Column1\`, etc. When\
> \`includeEmptyValues\` is true, missing values become JSON \`null\`\
> instead of being omitted from the record.\
> \
> When \`groupByFields\` is used the response shape changes: \`data\`\
> becomes an array of arrays (grouped records) and the\
> \`dataRecordTraceKeys\` / \`traceKeysDuplicate\` fields are omitted.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ParserResponse":{"type":"object","description":"Response from a parser processor (`csvParser`, `xmlParser`).\n\nWhen `groupByFields` is used in the request, the `dataRecordTraceKeys`\nand `traceKeysDuplicate` fields are omitted from the response and `data`\nbecomes an array of arrays (each inner array is one group of records).","required":["mediaType","data","duration"],"properties":{"mediaType":{"type":"string","description":"Always `json` for parser processors.","enum":["json"]},"data":{"description":"Parsed records. Normally an array of objects. When `groupByFields`\nis used, becomes an array of arrays (grouped records).","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries). Omitted\nwhen `groupByFields` is used."},"traceKeysDuplicate":{"type":"boolean","description":"Whether any duplicate trace keys were detected. Omitted when\n`groupByFields` is used."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/csvParser":{"post":{"operationId":"parseCsv","tags":["Parsers & Generators"],"summary":"Convert CSV to JSON","description":"Parses CSV data into JSON records using the specified delimiter and\nformatting rules.\n\nBoth `data` and `rules` are technically optional — omitting either\nreturns an empty result rather than an error. When `hasHeaderRow` is\nfalse, columns are named `Column0`, `Column1`, etc. When\n`includeEmptyValues` is true, missing values become JSON `null`\ninstead of being omitted from the record.\n\nWhen `groupByFields` is used the response shape changes: `data`\nbecomes an array of arrays (grouped records) and the\n`dataRecordTraceKeys` / `traceKeysDuplicate` fields are omitted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"The CSV data to parse."},"rules":{"type":"object","description":"Parsing rules controlling delimiters, headers, and grouping.","properties":{"columnDelimiter":{"type":"string","description":"Column delimiter character (e.g. `,`, `\\t`)."},"rowDelimiter":{"type":"string","description":"Row delimiter (e.g. `\\n`, `|`)."},"trimSpaces":{"type":"boolean","description":"Whether to trim leading/trailing spaces from values."},"hasHeaderRow":{"type":"boolean","description":"Whether the first row contains column headers. When false,\ncolumns are named Column0, Column1, etc."},"rowsPerRecord":{"type":"boolean"},"rowsToSkip":{"type":"integer","description":"Number of rows to skip before parsing begins."},"multipleRowsPerRecord":{"type":"boolean"},"disableQuoteAndStripEnclosingQuotes":{"type":"boolean"},"groupByFields":{"type":"array","items":{"type":"string"},"description":"Group parsed records by these field names. Changes the\nresponse `data` to an array of arrays and omits\n`dataRecordTraceKeys` and `traceKeysDuplicate`."},"sortByFields":{"type":"array","items":{"type":"string"}}}},"options":{"type":"object","properties":{"includeEmptyValues":{"type":"boolean","description":"When true, empty CSV values are returned as JSON `null`.\nWhen false (default), empty values are omitted from the\nrecord."}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Generate CSV from JSON

> Generates CSV output from JSON records using the specified delimiter\
> and formatting rules.\
> \
> The response always has \`mediaType: "text"\` and does not include\
> \`dataRecordTraceKeys\` or \`traceKeysDuplicate\`.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GeneratorResponse":{"type":"object","description":"Response from a generator processor (`csvDataGenerator`, `structuredFileGenerator`).","required":["mediaType","data","duration"],"properties":{"mediaType":{"type":"string","description":"Always `text` for generator processors.","enum":["text"]},"data":{"type":"string","description":"Generated text output (CSV, EDI, or other structured format)."},"duration":{"type":"integer","description":"Processing time in milliseconds."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/csvDataGenerator":{"post":{"operationId":"generateCsv","tags":["Parsers & Generators"],"summary":"Generate CSV from JSON","description":"Generates CSV output from JSON records using the specified delimiter\nand formatting rules.\n\nThe response always has `mediaType: \"text\"` and does not include\n`dataRecordTraceKeys` or `traceKeysDuplicate`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Records to convert to CSV. Accepts a flat array of objects\n(e.g. `[{\"a\":\"1\"}, {\"a\":\"2\"}]`) or an array of arrays for\nbatch processing (e.g. `[[{\"a\":\"1\"}], [{\"a\":\"2\"}]]`). Each\nobject's keys become column names when `includeHeader` is\ntrue.","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"rules":{"type":"object","description":"Generation rules controlling delimiters, headers, and\nformatting.","properties":{"columnDelimiter":{"type":"string","description":"Column delimiter character (e.g. `,`, `\\t`)."},"rowDelimiter":{"type":"string","description":"Row delimiter character (default `\\n`). Appended after\neach row including the last unless\n`truncateLastRowDelimiter` is true."},"includeHeader":{"type":"boolean","description":"Whether to include a header row with column names."},"truncateLastRowDelimiter":{"type":"boolean","description":"When true, omits the trailing row delimiter after the\nlast data row."},"replaceTabWithSpace":{"type":"boolean","description":"Replace tab characters in values with spaces."},"replaceNewlineWithSpace":{"type":"boolean","description":"Replace newline characters in values with spaces."},"wrapWithQuotes":{"type":"boolean","description":"Wrap every value (including headers) in double quotes."}}}}}}}},"responses":{"200":{"description":"Generated CSV data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratorResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Parse structured file (EDI) to JSON

> Parses EDI or other structured/delimited file data into JSON using\
> a file definition (parsing rules). Commonly used for X12 and EDIFACT\
> documents.\
> \
> The file definition must be provided inside a \`rules.fileDefinition\`\
> wrapper object, or referenced by ID via \`rules.\_fileDefinitionId\`.\
> This differs from the generator endpoint which places definition\
> fields directly in \`rules\`.\
> \
> The response includes a \`recordLevelErrors\` array not present on\
> other processor responses.\
> \
> \*\*Required file definition fields\*\* — \`name\`, \`version\` (string\
> \`"1"\` or \`"2"\`), \`format\` (\`delimited\`, \`delimited/x12\`,\
> \`delimited/edifact\`, or \`fixed\`), and the corresponding format\
> sub-object (\`delimited\` or \`fixed\`) with at least \`rowDelimiter\`\
> and \`colDelimiter\` (for delimited) or \`rowDelimiter\` and\
> \`paddingChar\` (for fixed). The \`rules\` property defines the\
> segment/element hierarchy.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"StructuredFileParserResponse":{"type":"object","description":"Response from the `structuredFileParser` processor.","required":["mediaType","data","recordLevelErrors","duration"],"properties":{"mediaType":{"type":"string","description":"Always `json` for the structured file parser.","enum":["json"]},"data":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Parsed records from the structured file."},"recordLevelErrors":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per-record errors encountered during parsing (e.g. missing required\nsegments or element validation failures)."},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries)."},"traceKeysDuplicate":{"type":"boolean","description":"Whether any duplicate trace keys were detected."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/structuredFileParser":{"post":{"operationId":"parseStructuredFile","tags":["Parsers & Generators"],"summary":"Parse structured file (EDI) to JSON","description":"Parses EDI or other structured/delimited file data into JSON using\na file definition (parsing rules). Commonly used for X12 and EDIFACT\ndocuments.\n\nThe file definition must be provided inside a `rules.fileDefinition`\nwrapper object, or referenced by ID via `rules._fileDefinitionId`.\nThis differs from the generator endpoint which places definition\nfields directly in `rules`.\n\nThe response includes a `recordLevelErrors` array not present on\nother processor responses.\n\n**Required file definition fields** — `name`, `version` (string\n`\"1\"` or `\"2\"`), `format` (`delimited`, `delimited/x12`,\n`delimited/edifact`, or `fixed`), and the corresponding format\nsub-object (`delimited` or `fixed`) with at least `rowDelimiter`\nand `colDelimiter` (for delimited) or `rowDelimiter` and\n`paddingChar` (for fixed). The `rules` property defines the\nsegment/element hierarchy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","rules"],"properties":{"data":{"type":"string","description":"The raw structured file content to parse."},"rules":{"type":"object","description":"Provide either a `fileDefinition` object with the full\ndefinition inline, or a `_fileDefinitionId` to reference\nan existing file definition resource.","properties":{"fileDefinition":{"type":"object","description":"Inline file definition. Must include `name`, `version`,\n`format`, the format-specific sub-object, and `rules`.","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string","enum":["1","2"]},"format":{"type":"string","description":"File format: `delimited`, `delimited/x12`,\n`delimited/edifact`, or `fixed`."},"delimited":{"type":"object","description":"Required when `format` starts with `delimited`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"colDelimiter":{"type":"string","description":"Column delimiter (required for delimited)."},"compositeDelimiter":{"type":"string","description":"Composite element delimiter (EDI formats)."}}},"fixed":{"type":"object","description":"Required when `format` is `fixed`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"paddingChar":{"type":"string","description":"Padding character (required, single char)."}}},"skipEmptyEndColDelimiter":{"type":"boolean"},"skipIntermittentEmptyLines":{"type":"boolean"},"skipEDIValidation":{"type":"boolean"},"skipEDIProfileValidation":{"type":"boolean"},"rules":{"description":"Segment/element hierarchy. Can be an array of\nsegment objects or a single root container object\nwith `children`.","oneOf":[{"title":"Segment array","type":"array","items":{"type":"object","additionalProperties":true}},{"title":"Root container","type":"object","additionalProperties":true}]}},"required":["name","version","format","rules"]},"_fileDefinitionId":{"type":"string","description":"Reference an existing file definition by ID instead of\nproviding an inline definition."},"resourcePath":{"type":"string","description":"Dot-separated path into the parsed document to select\nwhich segment's data to return as records."}}},"options":{"type":"object","properties":{"ediProfile":{"type":"object","additionalProperties":true,"description":"Optional EDI profile for ISA/GS envelope context."}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredFileParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"File definition validation error or missing required segment.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"source":{"type":"string"},"code":{"type":"string","description":"Error code. Common values: `file_definition_error`,\n`missing_row`, `WRONG_MAX_OCCURRENCE`."},"resolved":{"type":"boolean"},"occurredAt":{"type":"integer"},"path":{"type":"string"}}}}}}}}}}}
```

## Generate structured file (EDI) from JSON

> Generates EDI or other structured/delimited file content from JSON\
> records using a file definition (generation rules). Commonly used\
> for producing X12 and EDIFACT documents.\
> \
> Unlike the parser endpoint, the generator places file definition\
> fields directly in \`rules\` (no \`fileDefinition\` wrapper). Each\
> element in the definition must include a \`value\` property containing\
> the literal text to output for that field.\
> \
> The \`data\` field must be an array of objects. Each object in the\
> array represents one document to generate. The response has\
> \`mediaType: "text"\` and does not include \`dataRecordTraceKeys\` or\
> \`traceKeysDuplicate\`.\
> \
> \*\*Required file definition fields\*\* — \`name\`, \`version\` (string\
> \`"1"\` or \`"2"\`), \`format\`, the format sub-object with\
> \`rowDelimiter\` + \`colDelimiter\` (and optionally \`rowSuffix\`), and\
> \`rules\` defining segments with elements that each have \`name\` and\
> \`value\`.

```json
{"openapi":"3.1.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GeneratorResponse":{"type":"object","description":"Response from a generator processor (`csvDataGenerator`, `structuredFileGenerator`).","required":["mediaType","data","duration"],"properties":{"mediaType":{"type":"string","description":"Always `text` for generator processors.","enum":["text"]},"data":{"type":"string","description":"Generated text output (CSV, EDI, or other structured format)."},"duration":{"type":"integer","description":"Processing time in milliseconds."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/structuredFileGenerator":{"post":{"operationId":"generateStructuredFile","tags":["Parsers & Generators"],"summary":"Generate structured file (EDI) from JSON","description":"Generates EDI or other structured/delimited file content from JSON\nrecords using a file definition (generation rules). Commonly used\nfor producing X12 and EDIFACT documents.\n\nUnlike the parser endpoint, the generator places file definition\nfields directly in `rules` (no `fileDefinition` wrapper). Each\nelement in the definition must include a `value` property containing\nthe literal text to output for that field.\n\nThe `data` field must be an array of objects. Each object in the\narray represents one document to generate. The response has\n`mediaType: \"text\"` and does not include `dataRecordTraceKeys` or\n`traceKeysDuplicate`.\n\n**Required file definition fields** — `name`, `version` (string\n`\"1\"` or `\"2\"`), `format`, the format sub-object with\n`rowDelimiter` + `colDelimiter` (and optionally `rowSuffix`), and\n`rules` defining segments with elements that each have `name` and\n`value`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","rules"],"properties":{"data":{"type":"array","description":"Array of record objects. Each object represents one\ndocument to generate. The generator uses element `value`\nproperties from the rules, not field values from these\nobjects.","items":{"type":"object","additionalProperties":true}},"rules":{"type":"object","description":"File definition placed directly at this level (no\n`fileDefinition` wrapper). Must include `name`, `version`,\n`format`, the format sub-object, and `rules`.","required":["name","version","format","rules"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string","enum":["1","2"]},"format":{"type":"string","description":"File format: `delimited`, `delimited/x12`,\n`delimited/edifact`, or `fixed`."},"delimited":{"type":"object","description":"Required when `format` starts with `delimited`.","properties":{"rowSuffix":{"type":"string","description":"Appended after each row."},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"colDelimiter":{"type":"string","description":"Column delimiter (required for delimited)."},"compositeDelimiter":{"type":"string","description":"Composite element delimiter (EDI formats)."}}},"fixed":{"type":"object","description":"Required when `format` is `fixed`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"paddingChar":{"type":"string","description":"Padding character (required, single char)."}}},"skipEmptyEndColDelimiter":{"type":"boolean"},"rules":{"type":"array","description":"Array of segment definitions. Each segment has a `name`\nand `elements` array. Each element must have `name` and\n`value` (the literal text to output).","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"options":{"type":"object","properties":{"ediProfile":{"type":"object","additionalProperties":true,"description":"Optional EDI profile for ISA/GS envelope context."}}}}}}}},"responses":{"200":{"description":"Generated structured file content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratorResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"File definition validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"code":{"type":"string","description":"Error code. Typically `INVALID_FILE_DEFINITION` or\n`wrong_data_type`."},"message":{"type":"string"},"details":{"type":"array","description":"Detailed validation errors.","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"}}}},"path":{"type":"string"}}}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.celigo.com/api/api-reference/parsers-and-generators.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.