Skip to content

API Reference

This page shows how to use the Xtract Universal.iQ REST API.
Xtract Universal.iQ offers a REST API for listing configured services, querying service metadata, and executing services.

Base URL

The base URL uses the following format: [protocol]://[host or IP address]:[port].

Protocol Format Example
HTTP http://[host]:[port] http://localhost:8080
HTTPS https://[host]:[port] https://example.com:8080

The default port for both HTTP and HTTPS is 8080. For HTTPS, the server certificate provides the host name.

Endpoint Overview

All paths below are relative to the base URL:

Method Path Description
get-icon /api/v1/services List all services the caller has access to.
get-icon /api/v1/services/{serviceName}/details Get service metadata, including result-columns and parameters.
get-icon /api/v1/services/{serviceName}/swagger.json Get a service-specific Swagger 2.0 document.
get-icon /api/v1/services/{serviceName}/openapi.json Get a service-specific OpenAPI 3.2 document.
get-icon /api/v1/services/{serviceName}/run Run services synchronously with query parameters.
post-icon /api/v1/services/{serviceName}/run Run services synchronously with a JSON parameter object.
get-icon /api/v1/services/{serviceName}/start Start services asynchronously with query parameters.
post-icon /api/v1/services/{serviceName}/start Start services asynchronously with a JSON parameter object.

Note

The {serviceName} path parameter identifies existing Xtract Universal.iQ services. For services in folders, combine the folder name and service name with commas, e.g., the service KNA1 in the folder S4HANA is addressed as S4HANA,KNA1. The URL-encoded form S4HANA%2CKNA1 represents the same name.

HTTP Status Codes

Error responses use text/plain. The following table summarizes the status codes of the API:

Status Meaning
200 Request handled. When running services, this does not guarantee a successful data extraction.
400 Invalid request, e.g., an invalid service name or request data.
401 Authentication is required or the supplied credentials are invalid.
403 The caller lacks the required server or service access.
404 The requested service does not exist.
500 The server could not complete the request.

Run Services

Synchronous Execution

GET /api/v1/services/{serviceName}/run
POST /api/v1/services/{serviceName}/run

Starts a service run and waits for it to finish before returning a response. The response depends on the destination:

  • Pull destinations return data to the caller in the HTTP response. Examples include the HTTP and Microsoft Power BI destinations. The response contains JSON or CSV data, depending on the destination configuration.
  • Push destinations write SAP data to a target system, e.g., databases or storages. Examples include Microsoft SQL Server and Microsoft Azure Storage. The HTTP response contains run statistics, not the SAP records. The data is available in the target system.

Asynchronous Execution

GET /api/v1/services/{serviceName}/start
POST /api/v1/services/{serviceName}/start

Starts a service run and depending on the destination, returns a response immediately without waiting for the run to finish.

  • Pull destinations return data to the caller in the HTTP response. /start waits for the data to become available, then returns it as JSON or CSV instead of run statistics.
  • Push destinations write SAP data to a target system, e.g., databases or storages. /start returns a response immediately without waiting for the run to finish. The response contains the run statistics available at that time.

Runtime Parameters

The supported runtime parameter names and accepted values depend on the service configuration.

  • For GET, supply runtime parameters in the service URL, see Pass Query Parameters.
  • For POST, supply an optional JSON object that contains the runtime parameter names and values, see Pass Body Parameters. Set Content-Type: application/json.

For more information, see Parameter Overview or retrieve the parameter definitions of a service using Get Service Details.

Example Requests

The following requests use the service S4HANA,KNA1 to extract customer master data from an SAP table. The service supports the runtime parameters rows and whereClause. The examples omit authentication headers. Include them when required.

GET /api/v1/services/S4HANA,KNA1/run?rows=1000&whereClause=LAND1%20%3D%20%27DE%27 HTTP/1.1
Host: localhost:8080
Accept: application/json
POST /api/v1/services/S4HANA,KNA1/run HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json

{"rows":1000,"whereClause":"LAND1 = 'DE'"}
GET /api/v1/services/S4HANA,KNA1/start?rows=1000 HTTP/1.1
Host: localhost:8080
Accept: application/json
POST /api/v1/services/S4HANA,KNA1/start HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json

{"rows":1000}

Responses

The destination determines whether the response contains run statistics or SAP records:

  • Pull destinations return data to the caller in the HTTP response. Examples include the HTTP destination and the Microsoft Power BI connector. The response contains JSON or CSV data, depending on the destination configuration.
  • Push destinations write SAP data to a target system, e.g., database or storage locations. Examples include Microsoft SQL Server and Microsoft Azure Storage. The HTTP response contains run statistics, not the SAP records. The data is available in the target system.

Warning

Service finishes with errors despite HTTP 200 response
HTTP 200 means that the request was handled; it does not indicate that the extraction completed successfully.

The run-statistics can contain the following fields:

Field Type, when available Description
duration String Execution duration in ISO 8601 format.
rowsCount Integer Number of processed rows.
state String Current or final run state, e.g., FinishedNoErrors.
processId Integer Worker process identifier.
webLogTimestamp String Associated web-log timestamp.
extraction String Service name associated with the run.
destination String Destination connection name.
source String Source connection name.
sapStatistics Object SAP-specific statistics, when supplied by the source connector.
licenseNumber String License number associated with the run.
error String Error information reported by the run.
{
    "duration": "PT00H00M02.328S",
    "rowsCount": 2726,
    "state": "FinishedNoErrors",
    "webLogTimestamp": "2026-11-03_13:00:26.628",
    "extraction": [
        "S4HANA",
        "KNA1"
    ],
    "destination": [
        "azure_storage"
    ],
    "source": [
        "s4h"
    ],
    "sapStatistics": {
        "Version": 758,
        "DeploymentModel": "OnPrem",
        "SystemId": "10925025821593471230",
        "ApplicationServer": "7962283119924088786",
        "ProductName": "S4HANA ON PREMISE"
    }
}
[
    {
        "MANDT": "100",
        "KUNNR": "0000000313",
        "LAND1": "DE",
        "NAME1": "Theobald Software",
        "ORT01": "Stuttgart"
    },
    {
        "MANDT": "100",
        "KUNNR": "0000001824",
        "LAND1": "IN",
        "NAME1": "Acme Components India",
        "ORT01": "Bengaluru"
    }
]
KUNNR,LAND1,NAME1,ORT01
0000000313,DE,Theobald Software,Stuttgart
0000001824,IN,Acme Components India,Bengaluru

Get List of Services

GET /api/v1/services

Returns a list of all services the caller has access to. Services that cannot be read are omitted from the list.

Query Parameters

Parameter Required Description
destination No Filters services by connection type, e.g., MicrosoftFabricOneLake, Iceberg, AmazonS3, etc.

Response

Field Description
name Service name as a comma-separated path.
type Service type, e.g, Table, CDSFlow, etc.
source Source connection object with name and type (SapRfc or SapOdata).
destination Destination connection object with name and type.
created Creation information with timestamp and, when available, user.
lastChange Last-change information with timestamp and, when available, user.
sapObject Technical name of the extracted SAP object.
latestRun Latest-run summary with duration and state.

Example

GET http://localhost:8080/api/v1/services?destination=AmazonS3
{
    "services": [
        {
            "name": "S4HANA,KNA1",
            "type": "Table",
            "source": {
                "name": "s4h",
                "type": "SapRfc"
            },
            "destination": {
                "name": "s3",
                "type": "AmazonS3"
            },
            "created": {
                "user": "alice",
                "timestamp": "20261102T110438.462Z"
            },
            "lastChange": {
                "user": "bob",
                "timestamp": "20261103T133035.775Z"
            },
            "sapObject": "KNA1",
            "latestRun": {
                "duration": "PT00H00M00.031S",
                "state": "FinishedNoErrors"
            }
        }
    ]
}

Get Service Details

GET /api/v1/services/{serviceName}/details

Returns the metadata of a service, including result columns and runtime parameter definitions.

Response

Field Subfield Description
name
Name of the service, including the parent folder.
columns
Metadata of result columns.
name
Column name.
description
Column description, omitted when empty.
type
Runtime result representation, e.g., StringLengthMax, Decimal, or Date.
length
Column length.
isPrimaryKey
Indicates if the column is part of the primary key.
decimalsCount
Decimal places, included only for Decimal columns.
referenceField
Referenced SAP field, omitted when empty.
referenceTable
Referenced SAP table, omitted when empty.
parameters
Runtime parameter definitions contains two groups of parameters:
• service contains standard runtime parameters for the service type, e.g., whereClause for Table services.
• custom contains custom runtime parameters configured for the service. If no custom runtime parameters are defined, the custom group is omitted.
name
Name of the runtime parameter that can be used in execution requests.
description
Description of the parameter.
type
Data type of the parameter, e.g., Text or Number.
default
Optional default value.

Example

GET http://localhost:8080/api/v1/services/S4HANA,MARA/details
{
    "name": [
        "S4HANA",
        "MARA"
    ],
    "columns": [
        {
            "name": "MATNR",
            "description": "Material Number",
            "type": "StringLengthMax",
            "length": 40,
            "isPrimaryKey": true
        },
        {
            "name": "ERSDA",
            "description": "Created On",
            "type": "Date",
            "isPrimaryKey": false
        },
        {
            "name": "NTGEW",
            "description": "Net Weight",
            "type": "Decimal",
            "length": 13,
            "decimalsCount": 3,
            "isPrimaryKey": false,
            "referenceField": "GEWEI",
            "referenceTable": "MARA"
        }
    ],
    "parameters": {
        "service": [
            {
                "name": "packageSize",
                "description": "Rows per package",
                "type": "Number",
                "default": 50000
            },
            {
                "name": "rows",
                "description": "Total rows limit",
                "type": "Number",
                "default": 0
            },
            {
                "name": "whereClause",
                "description": "ABAP SQL WHERE clause",
                "type": "Text",
                "default": ""
            }
        ],
        "custom": [
            {
                "name": "myParameter",
                "description": "",
                "type": "Text",
                "default": null
            }
        ]
    }
}

Get Service API Descriptions

GET /api/v1/services/{serviceName}/swagger.json

Generates a Swagger 2.0 description for the requested service.

GET /api/v1/services/{serviceName}/openapi.json

Generates an OpenAPI 3.2 description for the requested service.

GET /api/v1/services/S4HANA,KNA1/swagger.json HTTP/1.1
Host: localhost:8080
Accept: text/plain
GET /api/v1/services/S4HANA,KNA1/openapi.json HTTP/1.1
Host: localhost:8080
Accept: text/plain

Last update: November 4, 2026