# File Definitions
## List file definitions
> Returns a list of all file definitions configured in the account.\
> If no file definitions exist, a 204 response with no body will be returned.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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"}},"parameters":{"Include":{"name":"include","in":"query","required":false,"description":"Comma-separated list of fields to project into each returned record.\nTriggers **summary projection** on supported list endpoints: the server\nreturns a minimal identity set for each record (`_id`, `name`, plus a\nresource-specific always-on set like `adaptorType` on exports/imports,\nor richer defaults on `ashares`, `audit`, `httpconnectors`, `transfers`,\netc.) and adds any listed fields that exist on the record. Listed fields\nthe record doesn't carry are silently dropped.\n\nDot notation is supported for projecting nested sub-fields — e.g.\n`include=ftp.directoryPath` on `/v1/exports` returns just that nested\nfield inside `ftp` for FTP-type exports (and omits `ftp` entirely for\nnon-FTP exports).\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n comma separator; digits are also accepted in practice. Any other\n character returns **400 `invalid_query_params`**.\n- Empty value (`include=`) or bare `include` is ignored — the full\n default record is returned.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n returns **400 `invalid_query_params`**: *\"Please provide either\n include or exclude param in the request query and not both.\"*\n- Array-bracket syntax (`include[]=...`) is not supported and can return\n a 500.\n- Only list endpoints honor projection — on GET-by-id the parameter is\n silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n `exclude` with **400 `invalid_query_params`** and a message of the form\n *\"Include or exclude query params are not applicable for ``\n resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to remove from the default response on\nsupported list endpoints. Unlike `include`, `exclude` does NOT trigger\nsummary projection — callers get the standard full-record shape with the\nnamed fields stripped out.\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n comma separator; digits are also accepted in practice. Any other\n character returns **400 `invalid_query_params`**.\n- Empty value (`exclude=`) is ignored.\n- Certain protected identity fields **cannot be stripped** — e.g.\n `exclude=name` on `/v1/exports` is silently ignored and `name` remains\n in the response. Protected sets vary per resource.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n returns **400 `invalid_query_params`**: *\"Please provide either\n include or exclude param in the request query and not both.\"*\n- Only list endpoints honor stripping — on GET-by-id the parameter is\n silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n `exclude` with **400 `invalid_query_params`** and a message of the form\n *\"Include or exclude query params are not applicable for ``\n resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}}},"schemas":{"Response":{"type":"object","description":"Response schema for file definition operations.\n\nContains the complete file definition configuration including metadata,\nformat settings, and parsing/generation rules.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the file definition"},"name":{"type":"string","description":"Human-readable name for the file definition"},"description":{"type":"string","description":"Description of the file definition's purpose"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition"},"format":{"type":"string","description":"File format (e.g., delimited, fixed, delimited/x12, delimited/edifact)"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents"},"globalId":{"type":"string","description":"Global identifier for EDI standard document definitions"},"rules":{"type":"array","description":"Hierarchical parsing/generation rules","items":{"type":"object","additionalProperties":true}},"fixed":{"type":"object","description":"Fixed-width format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"paddingChar":{"type":"string"}}},"delimited":{"type":"object","description":"Delimited format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"colDelimiter":{"type":"string"},"compositeDelimiter":{"type":"string"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows during parsing"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation"},"skipEDIProfileValidation":{"type":"boolean","description":"Whether to skip EDI profile-level validation"},"externalId":{"type":"string","description":"External identifier for this file definition"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this file definition belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this file definition is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this file definition was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the definition's origin"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was soft-deleted.\n\nOnly present for deleted definitions. The definition will be permanently\nremoved 30 days after this timestamp.\n"}}}},"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/filedefinitions":{"get":{"summary":"List file definitions","description":"Returns a list of all file definitions configured in the account.\nIf no file definitions exist, a 204 response with no body will be returned.\n","operationId":"listFileDefinitions","tags":["File Definitions"],"parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Successfully retrieved list of file definitions","headers":{"Link":{"description":"RFC-5988 pagination links. When more pages remain, includes a `<...>; rel=\"next\"` entry;\nabsent on the final page.\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"204":{"description":"No file definitions exist in the account"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```
## Create a file definition
> Creates a new file definition that describes the structure and parsing rules\
> for a structured file format.\
> \
> For EDI formats (\`delimited/x12\` or \`delimited/edifact\`), a valid \`globalId\`\
> is required when the account has an EDI license enabled. The \`globalId\` must\
> reference a known standard document definition.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n\nFile definitions describe the structure and parsing/generation rules for\nstructured file formats including delimited (CSV), fixed-width, EDI X12,\nand EDI EDIFACT.\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the file definition.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes. Stored in lowercase.\n\nCommon values:\n- **delimited**: Standard delimited files (CSV, TSV, etc.)\n- **delimited/x12**: EDI X12 format (requires `globalId` with EDI license)\n- **delimited/edifact**: EDI EDIFACT format (requires `globalId` with EDI license)\n- **fixed**: Fixed-width format\n"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents.\n\n- **997**: X12 functional acknowledgement\n- **CONTRL**: EDIFACT functional acknowledgement\n"},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"object","description":"Hierarchical parsing/generation rules that define the structure of the file.\n\nRules are recursive in nature and describe segments, elements, loops, and\ntheir relationships. The structure varies by format type. Maximum size: 20 KB.\n","additionalProperties":true},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}},"required":["name","version","format","rules"]},"Response":{"type":"object","description":"Response schema for file definition operations.\n\nContains the complete file definition configuration including metadata,\nformat settings, and parsing/generation rules.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the file definition"},"name":{"type":"string","description":"Human-readable name for the file definition"},"description":{"type":"string","description":"Description of the file definition's purpose"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition"},"format":{"type":"string","description":"File format (e.g., delimited, fixed, delimited/x12, delimited/edifact)"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents"},"globalId":{"type":"string","description":"Global identifier for EDI standard document definitions"},"rules":{"type":"array","description":"Hierarchical parsing/generation rules","items":{"type":"object","additionalProperties":true}},"fixed":{"type":"object","description":"Fixed-width format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"paddingChar":{"type":"string"}}},"delimited":{"type":"object","description":"Delimited format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"colDelimiter":{"type":"string"},"compositeDelimiter":{"type":"string"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows during parsing"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation"},"skipEDIProfileValidation":{"type":"boolean","description":"Whether to skip EDI profile-level validation"},"externalId":{"type":"string","description":"External identifier for this file definition"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this file definition belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this file definition is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this file definition was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the definition's origin"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was soft-deleted.\n\nOnly present for deleted definitions. The definition will be permanently\nremoved 30 days after this timestamp.\n"}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions":{"post":{"summary":"Create a file definition","description":"Creates a new file definition that describes the structure and parsing rules\nfor a structured file format.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`), a valid `globalId`\nis required when the account has an EDI license enabled. The `globalId` must\nreference a known standard document definition.\n","operationId":"createFileDefinition","tags":["File Definitions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"File definition created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```
## Get a file definition
> Returns the complete configuration of a specific file definition,\
> including its parsing rules and format settings.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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":{"Response":{"type":"object","description":"Response schema for file definition operations.\n\nContains the complete file definition configuration including metadata,\nformat settings, and parsing/generation rules.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the file definition"},"name":{"type":"string","description":"Human-readable name for the file definition"},"description":{"type":"string","description":"Description of the file definition's purpose"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition"},"format":{"type":"string","description":"File format (e.g., delimited, fixed, delimited/x12, delimited/edifact)"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents"},"globalId":{"type":"string","description":"Global identifier for EDI standard document definitions"},"rules":{"type":"array","description":"Hierarchical parsing/generation rules","items":{"type":"object","additionalProperties":true}},"fixed":{"type":"object","description":"Fixed-width format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"paddingChar":{"type":"string"}}},"delimited":{"type":"object","description":"Delimited format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"colDelimiter":{"type":"string"},"compositeDelimiter":{"type":"string"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows during parsing"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation"},"skipEDIProfileValidation":{"type":"boolean","description":"Whether to skip EDI profile-level validation"},"externalId":{"type":"string","description":"External identifier for this file definition"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this file definition belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this file definition is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this file definition was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the definition's origin"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was soft-deleted.\n\nOnly present for deleted definitions. The definition will be permanently\nremoved 30 days after this timestamp.\n"}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions/{_id}":{"get":{"summary":"Get a file definition","description":"Returns the complete configuration of a specific file definition,\nincluding its parsing rules and format settings.\n","operationId":"getFileDefinitionById","tags":["File Definitions"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the file definition","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"File definition retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## Update a file definition
> Updates an existing file definition with the provided configuration.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n\nFile definitions describe the structure and parsing/generation rules for\nstructured file formats including delimited (CSV), fixed-width, EDI X12,\nand EDI EDIFACT.\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the file definition.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes. Stored in lowercase.\n\nCommon values:\n- **delimited**: Standard delimited files (CSV, TSV, etc.)\n- **delimited/x12**: EDI X12 format (requires `globalId` with EDI license)\n- **delimited/edifact**: EDI EDIFACT format (requires `globalId` with EDI license)\n- **fixed**: Fixed-width format\n"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents.\n\n- **997**: X12 functional acknowledgement\n- **CONTRL**: EDIFACT functional acknowledgement\n"},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"object","description":"Hierarchical parsing/generation rules that define the structure of the file.\n\nRules are recursive in nature and describe segments, elements, loops, and\ntheir relationships. The structure varies by format type. Maximum size: 20 KB.\n","additionalProperties":true},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}},"required":["name","version","format","rules"]},"Response":{"type":"object","description":"Response schema for file definition operations.\n\nContains the complete file definition configuration including metadata,\nformat settings, and parsing/generation rules.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the file definition"},"name":{"type":"string","description":"Human-readable name for the file definition"},"description":{"type":"string","description":"Description of the file definition's purpose"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition"},"format":{"type":"string","description":"File format (e.g., delimited, fixed, delimited/x12, delimited/edifact)"},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents"},"globalId":{"type":"string","description":"Global identifier for EDI standard document definitions"},"rules":{"type":"array","description":"Hierarchical parsing/generation rules","items":{"type":"object","additionalProperties":true}},"fixed":{"type":"object","description":"Fixed-width format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"paddingChar":{"type":"string"}}},"delimited":{"type":"object","description":"Delimited format configuration","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string"},"colDelimiter":{"type":"string"},"compositeDelimiter":{"type":"string"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows during parsing"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation"},"skipEDIProfileValidation":{"type":"boolean","description":"Whether to skip EDI profile-level validation"},"externalId":{"type":"string","description":"External identifier for this file definition"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this file definition belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this file definition is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this file definition was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the definition's origin"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the file definition was soft-deleted.\n\nOnly present for deleted definitions. The definition will be permanently\nremoved 30 days after this timestamp.\n"}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions/{_id}":{"put":{"summary":"Update a file definition","description":"Updates an existing file definition with the provided configuration.\n","operationId":"updateFileDefinition","tags":["File Definitions"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the file definition","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"File definition updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## Delete a file definition
> Deletes a file definition. The definition is soft-deleted and retained\
> for 30 days before permanent removal.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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"}},"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"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/filedefinitions/{_id}":{"delete":{"summary":"Delete a file definition","description":"Deletes a file definition. The definition is soft-deleted and retained\nfor 30 days before permanent removal.\n","operationId":"deleteFileDefinition","tags":["File Definitions"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the file definition","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"File definition deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## List dependencies of a file definition
> Returns the set of resources that depend on the specified resource.\
> The response is an object whose keys are dependent-resource types\
> (e.g. \`flows\`, \`imports\`) and whose values are arrays of dependency\
> entries.\
> \
> AI guidance:\
> \- An empty object \`{}\` means no other resources depend on the target.\
> This is also returned for a well-formatted but nonexistent id.
```json
{"openapi":"3.1.0","info":{"title":"File Definitions","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":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"paths":{"type":"array","description":"JSON-path-style pointers within the dependent resource's document\nthat reference the target resource.\n","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of ids that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of id strings.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"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/filedefinitions/{_id}/dependencies":{"get":{"operationId":"listFileDefinitionDependencies","tags":["File Definitions"],"summary":"List dependencies of a file definition","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries.\n\nAI guidance:\n- An empty object `{}` means no other resources depend on the target.\n This is also returned for a well-formatted but nonexistent id.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```
---
# 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/file-definitions.md?ask=
```
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.