API reference

Conventions#

• The base path is /api. Swagger UI is at /swagger, with the spec at /api/swagger.json.
• Admin endpoints need Authorization: Bearer <jwt> from sign-in, plus the permission listed.
• Partner endpoints need a partner key instead: the key header (partnerkey unless renamed, and partnerkey always works), Authorization: Bearer <key>, or Basic auth. An API gateway set to take tokens needs Authorization: Bearer <token> from its login server.
• Responses use camelCase property names. Requests are accepted in any casing. Enums are strings, and numbers are accepted too.
• Adapter and partner property sets are lists of { "key": "...", "value": "..." }.

Errors#

Search queries#

Endpoints marked searchy accept these parameters.

They return { "result": [...], "totalCount": 123 }.

Partner endpoints#

See Entry points for status codes.

Session and account#

Connections#

All need the global values permissions: global-values.view to read, .create, .edit and .delete to change. Secrets come back as __private__.

Exchanges#

Exchange search filters, besides ordinary fields such as SubscriptionId, PartnerId and DocumentId. Those take rule 1 (is), 2 (is not) and 9 (is any of, as SubscriptionId:9:numeric|4|7). "Is none of" is one rule-2 filter per value. "Is not" keeps the exchanges with no value at all, for example no subscription.

Rule 2 turns each of these round except StatusFilter and LatestOnly: ErrorContains:2:timeout is "the error does not contain timeout", and it keeps the exchanges with no error. Each PromotedProperty turns round on its own. In the older form, send the key and the text with the same rule, since they turn round together.

Bulk retry takes { ids, filter, excludeIds, reason, reset }. filter is the same query-string fragment the search takes, such as filter=StatusFilter:1:3&filter=LatestOnly:1:true, and it replaces ids when present. The plan returned by both endpoints lists how many were selected and will be retried, attempts substituted with the end of their chain, and skipped exchanges with reasons, plus targets, the attempts that will run. The retry carries out at most limit (500) per request; the preview plans up to maxSelection (5,000), so a larger selection is retried by sending targets back as ids, limit at a time.

Export takes { ids, filter, excludeIds }, chosen the same way, and streams back a zip (application/zip) with a folder per exchange and a missing.txt listing files that storage no longer has. At most 500 exchanges go in one zip; a larger selection is refused with TOO_MANY. export/check takes the same body and returns { count, withoutFiles, keptDays }: how many exchanges the zip would take, how many of them are older than the bucket's rule keeps files, and that rule's days when one covers them all.

The retry tree returns { rootId, nodes, truncated }. Each node has its id, retryFor, promoted properties, times, status, exception, whether it was manual, and any scheduled retry or blocked reason. It stops at 100 levels or 500 attempts.

Subscriptions#

A scheduled job that pulls files from S3:

{
  "name": "Orders from S3",
  "type": "Receiving",
  "documentId": 3,
  "partnerId": 5,
  "receiverId": "NativeS3Receiver",
  "receiverProperties": [
    { "key": "ServiceUrl", "value": "https://s3.example.com" },
    { "key": "BucketName", "value": "incoming" },
    { "key": "AccessKeyId", "value": "{{globals.s3.accessKeyId}}" },
    { "key": "SecretAccessKey", "value": "{{globals.s3.secretAccessKey}}" }
  ],
  "handlerId": "NativeHttpHandler",
  "handlerProperties": [ { "key": "Url", "value": "{{partner.erpUrl}}/orders" } ],
  "schedules": [ { "recurrence": "Hourly", "days": 0, "hours": 0, "minutes": 15 } ],
  "retryPolicyId": 1,
  "inactive": false
}

A subscription bound to a data source also carries dataSourceId.

expectTraffic asks to be told when the subscription stops receiving exchanges. See Entry points. It is replaced like the rest of the configuration, so an update without it removes it.

"expectTraffic": { "everyMinutes": 15, "days": ["Sun", "Mon", "Tue", "Wed", "Thu"], "from": "08:00", "to": "22:00", "timeZone": "Asia/Riyadh" }

A value that breaks a rule is refused with a validation error whose message says which. GET /api/subscriptions/{id} and the search also return quietSince: when the subscription was found quiet, or null. It can't be set through the API.

notifications sends through notification channels when the subscription's exchanges finish or it goes quiet. Unlike the rest, leaving it out of an update keeps the stored rows; an empty list clears them.

"notifications": [ { "channelId": 4, "onFailure": true, "onBadResult": false, "onSuccess": false, "onQuiet": true } ]

Adapters and mapping#

Adapter descriptions are cached per node. Publishing, promoting or withdrawing through the API clears them on every node; a package published straight to storage shows its old properties for up to a minute.

Publishing a package, promoting, withdrawing, and publishing from a draft are recorded in the audit trail as AdapterRelease rows. Drafts are recorded as AdapterDraft rows, with a hash of their files rather than the files.

Gateways#

Data sources#

See Data sources and Databases.

Configuration#

Administration#

Monitoring#