--- title: Create or update ingest schema slug: reference/create-or-update-ingest-schema docTags: createdAt: 2025-01-21T18:39:14.860Z --- { "id": "kM4j3xA-D0rwhwwu2-1OS", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://app.amberflo.io/ingest/settings/ingest-schema", "servers": [ { "url": "https://app.amberflo.io/ingest/settings/ingest-schema" } ], "name": "Create or update ingest schema", "description": "

Creates or updates an ingest schema for transforming custom data formats into meter events.

\n

Schemas define transformation nodes that extract meter event fields from your source data:

\n\n

Include validation rules and conditional logic to handle data variations. Test schemas thoroughly before production use.

\n

The schema defines transformation nodes for extracting customer IDs, meter names, event times, values, and custom dimensions from your source data format.

\n

Important: Schema changes may affect existing event ingestion pipelines. Test thoroughly before deploying to production.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "Schema configuration for parsing and transforming ingested messages with optional conditional application", "customType": "ingestion.settings.IngestMessageSchema.in", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for the schema configuration used in message processing", "example": "" }, { "name": "schema", "kind": "required", "type": "object", "description": "Schema structure definition specifying how to parse and extract data from messages", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ExplodeNode.in", "customType": "ingestion.schema_adapters.nodes.ExplodeNode.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as an explode/expansion node", "example": "", "default": "explode" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message containing the array or object to explode", "example": "" }, { "name": "subComponents", "kind": "optional", "type": "object", "description": "Array of schema extractor nodes defining how to process each exploded element", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.SchemaExtractorNode.in", "customType": "ingestion.schema_adapters.nodes.SchemaExtractorNode.in[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.nodes.CustomerIdNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.CustomerIdNode.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as a customer ID extraction node", "example": "", "default": "customer_id" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the customer ID", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.DimensionNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.DimensionNode.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as a dimension extraction node", "example": "", "default": "dimension" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the dimension value", "example": "" }, { "name": "targetName", "kind": "optional", "type": "string", "description": "Target dimension name to assign the extracted value in the resulting meter event", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.EventTimeNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.EventTimeNode.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as an event time extraction node", "example": "", "default": "event_time" }, { "name": "timeFormat", "kind": "optional", "type": "string", "description": "Time format specification for parsing the source timestamp value", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.TimeFormat.in", "customType": "ingestion.schema_adapters.nodes.TimeFormat.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the timestamp", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.ExplodeNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ExplodeNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.ForkNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ForkNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.MeterApiNameNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.MeterApiNameNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.ValueNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ValueNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.SameElementArrayNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.SameElementArrayNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.UniqueIdNode.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.UniqueIdNode.in", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] } ] } ] }, { "name": "condition", "kind": "optional", "type": "object", "description": "Optional condition for applying schema. Used to evaluate if schema should be applied", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.MatchCondition.in", "customType": "ingestion.schema_adapters.conditions.MatchCondition.in", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.conditions.NotCondition.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.NotCondition.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a negation condition", "example": "", "default": "not" }, { "name": "condition", "kind": "required", "type": "object", "description": "The nested condition whose result will be inverted by this negation operator", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.MatchCondition.in", "customType": "ingestion.schema_adapters.conditions.MatchCondition.in", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.conditions.NotCondition.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.NotCondition.in", "schema": [ { "name": "", "description": "", "customType": "Circular-Reference" } ] }, { "name": "ingestion.schema_adapters.conditions.ValidIdentifierCondition.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.ValidIdentifierCondition.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a valid identifier validation condition", "example": "", "default": "valid_identifier" }, { "name": "fieldName", "kind": "required", "type": "string", "description": "Name of the field in the message to validate against the list of valid values", "example": "" }, { "name": "validValues", "kind": "required", "type": "array", "description": "Array of acceptable string values that the specified field must match for condition to be true", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] } ] }, { "name": "ingestion.schema_adapters.conditions.ValidIdentifierCondition.in", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.ValidIdentifierCondition.in", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a valid identifier validation condition", "example": "", "default": "valid_identifier" }, { "name": "fieldName", "kind": "required", "type": "string", "description": "Name of the field in the message to validate against the list of valid values", "example": "" }, { "name": "validValues", "kind": "required", "type": "array", "description": "Array of acceptable string values that the specified field must match for condition to be true", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] }, { "name": "autoDetectable", "kind": "optional", "type": "boolean", "description": "Whether the schema can be used in schema auto-detection. Can only be true if schema has condition", "example": "" } ], "modelRef": "#/components/schemas/ingestion.settings.IngestMessageSchema.in", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "X-API-KEY", "kind": "optional", "type": "apiKey", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "Successful request", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Schema configuration for parsing and transforming ingested messages with metadata and conditional application", "customType": "ingestion.settings.IngestMessageSchema.out", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for the schema configuration used in message processing", "example": "" }, { "name": "createTimeInSeconds", "kind": "optional", "type": "integer", "description": "Create time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds)", "example": 0 }, { "name": "updateTimeInSeconds", "kind": "optional", "type": "integer", "description": "Update time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds)", "example": 0 }, { "name": "schema", "kind": "required", "type": "object", "description": "Schema structure definition specifying how to parse and extract data from messages", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ExplodeNode.out", "customType": "ingestion.schema_adapters.nodes.ExplodeNode.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as an explode/expansion node", "example": "", "default": "explode" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message containing the array or object to explode", "example": "" }, { "name": "subComponents", "kind": "optional", "type": "object", "description": "Array of schema extractor nodes defining how to process each exploded element", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.SchemaExtractorNode.out", "customType": "ingestion.schema_adapters.nodes.SchemaExtractorNode.out[]", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.nodes.CustomerIdNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.CustomerIdNode.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as a customer ID extraction node", "example": "", "default": "customer_id" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the customer ID", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.DimensionNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.DimensionNode.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as a dimension extraction node", "example": "", "default": "dimension" }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the dimension value", "example": "" }, { "name": "targetName", "kind": "optional", "type": "string", "description": "Target dimension name to assign the extracted value in the resulting meter event", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.EventTimeNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.EventTimeNode.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Node type identifier specifying this as an event time extraction node", "example": "", "default": "event_time" }, { "name": "timeFormat", "kind": "optional", "type": "string", "description": "Time format specification for parsing the source timestamp value", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.TimeFormat.out", "customType": "ingestion.schema_adapters.nodes.TimeFormat.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "sourceName", "kind": "optional", "type": "string", "description": "Field name or path in the source message from which to extract the timestamp", "example": "" } ] }, { "name": "ingestion.schema_adapters.nodes.ExplodeNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ExplodeNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.ForkNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ForkNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.MeterApiNameNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.MeterApiNameNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.ValueNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.ValueNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.SameElementArrayNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.SameElementArrayNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "ingestion.schema_adapters.nodes.UniqueIdNode.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.nodes.UniqueIdNode.out", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] } ] } ] }, { "name": "condition", "kind": "optional", "type": "object", "description": "Optional condition for applying schema. Used to evaluate if schema should be applied", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.MatchCondition.out", "customType": "ingestion.schema_adapters.conditions.MatchCondition.out", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.conditions.NotCondition.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.NotCondition.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a negation condition", "example": "", "default": "not" }, { "name": "condition", "kind": "required", "type": "object", "description": "The nested condition whose result will be inverted by this negation operator", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.MatchCondition.out", "customType": "ingestion.schema_adapters.conditions.MatchCondition.out", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ingestion.schema_adapters.conditions.NotCondition.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.NotCondition.out", "schema": [ { "name": "", "description": "", "customType": "Circular-Reference" } ] }, { "name": "ingestion.schema_adapters.conditions.ValidIdentifierCondition.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.ValidIdentifierCondition.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a valid identifier validation condition", "example": "", "default": "valid_identifier" }, { "name": "fieldName", "kind": "required", "type": "string", "description": "Name of the field in the message to validate against the list of valid values", "example": "" }, { "name": "validValues", "kind": "required", "type": "array", "description": "Array of acceptable string values that the specified field must match for condition to be true", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] } ] }, { "name": "ingestion.schema_adapters.conditions.ValidIdentifierCondition.out", "description": "", "modelRef": "#/components/schemas/ingestion.schema_adapters.conditions.ValidIdentifierCondition.out", "schema": [ { "name": "type", "kind": "optional", "type": "string", "description": "Condition type identifier specifying this as a valid identifier validation condition", "example": "", "default": "valid_identifier" }, { "name": "fieldName", "kind": "required", "type": "string", "description": "Name of the field in the message to validate against the list of valid values", "example": "" }, { "name": "validValues", "kind": "required", "type": "array", "description": "Array of acceptable string values that the specified field must match for condition to be true", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] }, { "name": "autoDetectable", "kind": "optional", "type": "boolean", "description": "Whether the schema can be used in schema auto-detection. Can only be true if schema has condition", "example": "" } ], "modelRef": "#/components/schemas/ingestion.settings.IngestMessageSchema.out", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "9VoR0V1t3PeZ3lFDysrtJ", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/ingest/settings/ingest-schema \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"schema\": {\n \"type\": \"explode\",\n \"subComponents\": {\n \"type\": \"customer_id\"\n }\n },\n \"condition\": {\n \"type\": \"not\",\n \"condition\": {}\n }\n }'" }, { "id": "SFqU8ZF_Iju_DujwP2Q8Q", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"schema\": {\n \"type\": \"explode\",\n \"subComponents\": {\n \"type\": \"customer_id\"\n }\n },\n \"condition\": {\n \"type\": \"not\",\n \"condition\": {}\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/ingest/settings/ingest-schema\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "DtjLBzodO9DZNHokfS-0a", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/ingest/settings/ingest-schema\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"schema\": {\n \"type\": \"explode\",\n \"subComponents\": {\n \"type\": \"customer_id\"\n }\n },\n \"condition\": {\n \"type\": \"not\",\n \"condition\": {}\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "koztSSUoLy1gGr8a4PdYe", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/ingest/settings/ingest-schema\"\n\npayload = json.dumps({\n \"schema\": {\n \"type\": \"explode\",\n \"subComponents\": {\n \"type\": \"customer_id\"\n }\n },\n \"condition\": {\n \"type\": \"not\",\n \"condition\": {}\n }\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "9VoR0V1t3PeZ3lFDysrtJ" }, "results": { "languages": [ { "id": "r_DybulGx4mGBLTjP_TgT", "language": "200", "code": "// Successful request\n{\n \"id\": \"\",\n \"createTimeInSeconds\": \"\",\n \"updateTimeInSeconds\": \"\",\n \"schema\": {\n \"type\": \"\",\n \"sourceName\": \"\",\n \"subComponents\": {}\n },\n \"condition\": {},\n \"autoDetectable\": false\n}" } ], "selectedLanguageId": "r_DybulGx4mGBLTjP_TgT" } }, "children": [ { "text": "", "id": "O2Fr3zpkuvIBtiZorkliw" } ] }