> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/api-guides/utilities/import-service/api-reference/streams.md). # Streams Read the streams of a configuration. ## Retrieving all streams of a configuration > \

\\

\ > \ > {% hint style="danger" %}\ > This functionality is in preview mode - some of the features may not be fully operational yet.\ > {% endhint %}\ > \ > Retrieves the streams belonging to a configuration, ordered by sequence. ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Streams","description":"Read the streams of a configuration."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"ImportStream":{"title":"Stream","type":"object","description":"A stream that extracts from a source, maps fields, and upserts into an Emporix target type.","properties":{"id":{"type":"string","format":"uuid","description":"The stream identifier."},"configId":{"type":"string","format":"uuid","description":"The parent configuration."},"name":{"type":"string","description":"The stream name."},"sourceEntity":{"type":"string","description":"The logical source entity or record."},"targetWriter":{"type":"string","description":"The target writer code, for example `emporix.customEntity`."},"targetType":{"type":"string","description":"The default target type (custom-entity type identifier)."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE"],"description":"How the stream contributes to the target."},"deltaField":{"type":"string","description":"The source field whose value is tracked as the delta watermark. A delta run extracts only the records whose value is newer than the last run's."},"deltaFieldFormat":{"type":"string","enum":["DATE","UNIX_SECONDS","UNIX_MILLIS"],"description":"How the delta field's values are formatted, so they can be compared correctly."},"compositeParent":{"type":"string","description":"For a composite child stream, the name of the stream it contributes to."},"linkingField":{"type":"string","description":"For a composite child stream, the source field holding its parent's key."},"embedAttribute":{"type":"string","description":"For a composite child stream, the parent attribute its records are embedded into."},"childStrategy":{"type":"string","enum":["EMBED","PATCH"],"description":"How a composite child's records reach the parent object."},"writeStrategy":{"type":"string","enum":["PATCH","MERGE_PUT","REPLACE_PUT"],"description":"How an existing target object is updated. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared."},"discriminatorField":{"type":"string","description":"A source field whose value routes each record to a different target type, as defined by `discriminatorMap`."},"discriminatorMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Maps a discriminator value to the target type that receives those records."},"targetDeleteSubscriptionEnabled":{"type":"boolean","description":"Whether the stream reacts to its target objects being deleted outside the import."},"onTargetReappear":{"type":"string","enum":["IGNORE","READD"],"description":"What happens when a record deleted in the target is seen in the source again."},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdAt":{"type":"string","format":"date-time","description":"When the stream was created."},"enabled":{"type":"boolean","description":"Whether the stream is active."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/importtool/{tenant}/configs/{configId}/streams":{"get":{"summary":"Retrieving all streams of a configuration","description":"

\"\"

\n\n{% hint style=\"danger\" %}\nThis functionality is in preview mode - some of the features may not be fully operational yet.\n{% endhint %}\n\nRetrieves the streams belonging to a configuration, ordered by sequence.","operationId":"GET-importtool-list-streams","tags":["Streams"],"responses":{"200":{"description":"The request was successful. The streams are returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImportStream"}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}} ``` ## Retrieving a stream > \

\\

\ > \ > {% hint style="danger" %}\ > This functionality is in preview mode - some of the features may not be fully operational yet.\ > {% endhint %}\ > \ > Retrieves a single stream by its identifier, including its resolved target types. ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Streams","description":"Read the streams of a configuration."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"ImportStream":{"title":"Stream","type":"object","description":"A stream that extracts from a source, maps fields, and upserts into an Emporix target type.","properties":{"id":{"type":"string","format":"uuid","description":"The stream identifier."},"configId":{"type":"string","format":"uuid","description":"The parent configuration."},"name":{"type":"string","description":"The stream name."},"sourceEntity":{"type":"string","description":"The logical source entity or record."},"targetWriter":{"type":"string","description":"The target writer code, for example `emporix.customEntity`."},"targetType":{"type":"string","description":"The default target type (custom-entity type identifier)."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE"],"description":"How the stream contributes to the target."},"deltaField":{"type":"string","description":"The source field whose value is tracked as the delta watermark. A delta run extracts only the records whose value is newer than the last run's."},"deltaFieldFormat":{"type":"string","enum":["DATE","UNIX_SECONDS","UNIX_MILLIS"],"description":"How the delta field's values are formatted, so they can be compared correctly."},"compositeParent":{"type":"string","description":"For a composite child stream, the name of the stream it contributes to."},"linkingField":{"type":"string","description":"For a composite child stream, the source field holding its parent's key."},"embedAttribute":{"type":"string","description":"For a composite child stream, the parent attribute its records are embedded into."},"childStrategy":{"type":"string","enum":["EMBED","PATCH"],"description":"How a composite child's records reach the parent object."},"writeStrategy":{"type":"string","enum":["PATCH","MERGE_PUT","REPLACE_PUT"],"description":"How an existing target object is updated. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared."},"discriminatorField":{"type":"string","description":"A source field whose value routes each record to a different target type, as defined by `discriminatorMap`."},"discriminatorMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Maps a discriminator value to the target type that receives those records."},"targetDeleteSubscriptionEnabled":{"type":"boolean","description":"Whether the stream reacts to its target objects being deleted outside the import."},"onTargetReappear":{"type":"string","enum":["IGNORE","READD"],"description":"What happens when a record deleted in the target is seen in the source again."},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdAt":{"type":"string","format":"date-time","description":"When the stream was created."},"enabled":{"type":"boolean","description":"Whether the stream is active."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/importtool/{tenant}/streams/{id}":{"get":{"summary":"Retrieving a stream","description":"

\"\"

\n\n{% hint style=\"danger\" %}\nThis functionality is in preview mode - some of the features may not be fully operational yet.\n{% endhint %}\n\nRetrieves a single stream by its identifier, including its resolved target types.","operationId":"GET-importtool-get-stream","tags":["Streams"],"responses":{"200":{"description":"The request was successful. The stream is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportStream"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-references/api-guides/utilities/import-service/api-reference/streams.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.