Emporix Streams API

openapi: 3.2.0
info:
  title: Emporix Streams API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Streams across 2 of this provider''s published API definitions: emporix-import-service-openapi.yml, emporix-import-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2:
  - importtool.import_trigger
tags:
- name: Streams
  description: Read the streams of a configuration.
paths:
  /importtool/{tenant}/configs/{configId}/streams:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - $ref: '#/components/parameters/trait_configId'
    get:
      summary: Retrieving all streams of a configuration
      description: Retrieves the streams belonging to a configuration, ordered by sequence.
      operationId: GET-importtool-list-streams
      tags:
      - Streams
      security:
      - OAuth2:
        - importtool.import_trigger
      responses:
        '200':
          description: The request was successful. The streams are returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ImportStream'
              examples:
                Streams response:
                  $ref: '#/components/examples/ImportStreams_Example'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    servers:
    - url: https://api.emporix.io
  /importtool/{tenant}/streams/{id}:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - $ref: '#/components/parameters/trait_id'
    get:
      summary: Retrieving a stream
      description: Retrieves a single stream by its identifier, including its resolved target types.
      operationId: GET-importtool-get-stream
      tags:
      - Streams
      security:
      - OAuth2:
        - importtool.import_trigger
      responses:
        '200':
          description: The request was successful. The stream is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStream'
              examples:
                Stream response:
                  $ref: '#/components/examples/ImportStream_Example'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    servers:
    - url: https://api.emporix.io
  /importtool/{tenant}/configs/{configId}/stream-order:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - $ref: '#/components/parameters/trait_configId'
    get:
      summary: Retrieving the stream run order
      description: 'Retrieves the order in which the configuration''s streams run, and the dependencies behind that order.


        Dependencies between streams decide the order. Sequence breaks ties.


        Dependencies come from four sources:


        * an explicit dependency on another stream

        * a mapping that references a type another stream produces

        * a `COMPOSITE_CHILD` stream with `childStrategy` set to `EMBED` – runs before the parent that embeds it

        * a `COMPOSITE_CHILD` stream with `childStrategy` set to `PATCH`, or a `COMPOSITE_MERGE` stream – run after the parent they update


        Use this endpoint rather than calculating the order yourself. Mapping transformations add

        dependencies that a single stream definition does not show. An order calculated without those

        dependencies can differ from the order used at run time.'
      operationId: GET-importtool-stream-order
      tags:
      - Streams
      security:
      - OAuth2:
        - importtool.import_trigger
      responses:
        '200':
          description: The request was successful. The stream order is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    type: array
                    items:
                      type: string
                    description: Stream names in the order they run.
                  prereqs:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: For each stream name, the streams that must run before it. A stream with no dependencies has an empty list.
              examples:
                Stream order:
                  value:
                    order:
                    - vendor
                    - purchaseOrder
                    - purchaseOrderLine
                    prereqs:
                      vendor: []
                      purchaseOrder:
                      - vendor
                      purchaseOrderLine:
                      - purchaseOrder
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    servers:
    - url: https://api.emporix.io
components:
  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
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    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'
          examples:
            Access to resource is forbidden:
              $ref: '#/components/examples/Forbidden403_Example'
    NotFound_404:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Resource not found:
              $ref: '#/components/examples/NotFound404_Example'
    InternalServiceError_500:
      description: Internal Service Error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Internal service error:
              $ref: '#/components/examples/InternalServiceError500_Example'
  schemas:
    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`.
          example: 0.01
        failureRatioRed:
          type: number
          format: double
          description: The share of failed records (0..1) at or above which the stream is `RED`.
          example: 0.1
        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.
          example: 48
        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.
          example: 168
        failedRunIsRed:
          type: boolean
          description: Whether a failed most-recent run makes the stream `RED` regardless of the other limits.
          example: true
    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
    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.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        configId:
          type: string
          format: uuid
          description: The parent configuration.
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        name:
          type: string
          description: The stream name.
          example: Products
        sourceEntity:
          type: string
          description: The logical source entity or record.
          example: PRODUCT
        targetWriter:
          type: string
          description: The target writer code, for example `emporix.customEntity`.
          example: emporix.customEntity
        targetType:
          type: string
          description: The default target type (custom-entity type identifier).
          example: product
        mode:
          type: string
          enum:
          - STANDALONE
          - COMPOSITE_CHILD
          - COMPOSITE_MERGE
          description: How the stream contributes to the target.
          example: STANDALONE
        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.
          example: LASTCHANGEDATE
        deltaFieldFormat:
          type: string
          enum:
          - DATE
          - UNIX_SECONDS
          - UNIX_MILLIS
          description: How the delta field's values are formatted, so they can be compared correctly.
          example: DATE
        compositeParent:
          type: string
          description: For a composite child stream, the name of the stream it contributes to.
          example: invoices
        linkingField:
          type: string
          description: For a composite child stream, the source field holding its parent's key.
          example: INVOICE_ID
        embedAttribute:
          type: string
          description: For a composite child stream, the parent attribute its records are embedded into.
          example: lineItems
        childStrategy:
          type: string
          enum:
          - EMBED
          - PATCH
          description: How a composite child's records reach the parent object.
          example: EMBED
        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.
          example: PATCH
        discriminatorField:
          type: string
          description: A source field whose value routes each record to a different target type, as defined by `discriminatorMap`.
          example: DOCUMENT_TYPE
        discriminatorMap:
          type: object
          additionalProperties:
            type: string
          description: Maps a discriminator value to the target type that receives those records.
          example:
            PO Invoice: PO_INVOICE
            Non PO Invoice: NON_PO_INVOICE
        deleteConfig:
          type: object
          description: 'How deletes are detected in the source and propagated to the target. Omit for an upsert-only

            stream. `MARKER`: a field on the record flags it as deleted. `TOMBSTONE`: a separate source

            record lists the deleted IDs.'
          properties:
            mode:
              type: string
              enum:
              - MARKER
              - TOMBSTONE
              description: How a deleted record is recognised.
            markerField:
              type: string
              description: '`MARKER` only. The source field that flags a record as deleted.'
            markerValues:
              type: array
              items:
                type: string
              description: '`MARKER` only. The values of `markerField` that mean deleted.'
            record:
              type: string
              description: '`TOMBSTONE` only. The explicit name of the source record that lists deleted IDs. Omit this

                property when the name can be derived from the imported record by adding a prefix or suffix —

                for example, `invoice_deleted` for an `invoice` stream. Specify it when the deletion record

                does not follow that naming convention.'
          example:
            mode: MARKER
            markerField: DELETIONINDICATOR
            markerValues:
            - X
        healthThresholds:
          $ref: '#/components/schemas/HealthThresholds'
        createdAt:
          type: string
          format: date-time
          description: When the stream was created.
          example: '2024-05-01T09:00:00.000Z'
        enabled:
          type: boolean
          description: Whether the stream is active.
          example: true
  examples:
    ImportStreams_Example:
      value:
      - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        configId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        name: Products
        sourceEntity: PRODUCT
        targetWriter: emporix.customEntity
        targetType: product
        mode: STANDALONE
        enabled: true
    NotFound404_Example:
      value:
        status: element_resource_non_existing
        code: 404
        message: The requested resource does not exist.
    Forbidden403_Example:
      value:
        status: forbidden
        code: 403
        message: The access to the requested resource has been forbidden.
        details:
        - Missing required scopes
    ImportStream_Example:
      value:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        configId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        name: Products
        sourceEntity: PRODUCT
        targetWriter: emporix.customEntity
        targetType: product
        mode: STANDALONE
        enabled: true
    InternalServiceError500_Example:
      value:
        status: internal_service_error
        code: 500
        message: A server-side exception occurred that prevented the system from correctly returning the result.
        details:
        - https://pattern.yaas.io/errortypes.html
  parameters:
    trait_id:
      name: id
      in: path
      required: true
      description: The resource identifier.
      schema:
        type: string
        format: uuid
        example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    trait_configId:
      name: configId
      in: path
      required: true
      description: The configuration identifier.
      schema:
        type: string
        format: uuid
        example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: 'The tenant you want to access.

        '
      schema:
        type: string
        example: mytenant
  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.
x-refined-from:
- emporix-import-service-openapi.yml
- emporix-import-service-openapi.yml