--- title: "listIntegrationsV2" method: GET path: "/v2/integrations" tags: ["integrations"] --- # listIntegrationsV2 `GET /v2/integrations` Retrieve all integrations with embedded use cases for the authenticated organization ## Response `200` Successfully retrieved integrations with use cases - object - `integrations` IntegrationWithUseCases[], required - `id` string, uuid, required — Unique identifier for the integration - `orgId` string, required — Organization ID - `created_at` string, date-time, required — ISO-8601 timestamp when the integration was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the integration was last updated - `name` string, required — Integration name - `description` string — Optional description of the integration - `access_token_ids` string[] — List of access token IDs associated with this integration - `app_ids` string[] — List of app IDs associated with this integration - `environment_config` EnvironmentFieldConfig[] — Configuration defining environment variables needed by this integration. Values are stored in the Environments API. - `key` string, required — Environment variable key, used to look up the value in the Environments API. - `label` string, required — Display label for the field in the UI - `type` 'String' | 'SecretString', required — Whether the value is a plain string or an encrypted secret - `description` string — Help text shown below the field - `required` boolean — Whether this field must be filled before the integration can be used - `order` integer — Sort order for display and drag-to-reorder - `settings` IntegrationSettings — Settings for the integration - `autoRefresh` AutoRefreshSettings — Auto-refresh settings for keeping integration data fresh - `enabled` boolean — Whether auto-refresh is enabled - `freshnessThresholdMinutes` integer — Maximum age (in minutes) of data before it is considered stale and eligible for refresh - `notifications` IntegrationNotificationConfig — Integration monitoring notification configuration. Rides Integration.settings.notifications (camelCase) and surfaces on both v1 and v2 GET/PUT. Unknown keys are stripped server-side to stay forward-compatible with deferred (V2) rule types. - `enabled` boolean, required — Master switch for this integration's notifications. - `recipients` NotificationRecipient[], required — epilot user ids notified for this integration. Same-org membership and per-user notification preferences are enforced at send time (Phases 3–5), not at config-write time. - `user_id` string, required — epilot user id. Same-org membership is enforced at send time (Phases 3–5), which re-validates each recipient against the integration's org before fanning out — it is not enforced at config-write time. - `defaultChannels` NotificationChannelSet, required — Delivery channel toggles. New channels added in svc-notification-api inherit here. - `email` boolean, required - `in_app` boolean, required - `monitoredUseCases` string[] — Integration-level use-case include-filter; absent/empty means all use cases. - `monitoredCodes` string[] — Integration-level code scope; absent/empty resolves to ['_error_']. Accepts concrete monitoring error codes or group sentinels (_error_, _warning_, _success_, _info_, _any_, _parent_). - `rules` NotificationRule[], required — Enabled triggers and their params. A type MAY repeat; capped at 20 rules (enforced at the write boundary). - `id` string — Stable AlertState + baseline key. Optional on write — the server mints a ULID when omitted; a supplied id is preserved verbatim. - `name` string — Optional human label disambiguating two rules of the same type. - `type` 'critical_error' | 'error_threshold' | 'warning_threshold' | 'success_rate_drop' | 'recovery' | 'silence', required — Rule trigger type. These are the only supported types; each is produced by a real alerter. - `enabled` boolean, required - `channels` NotificationChannelSet — Delivery channel toggles. New channels added in svc-notification-api inherit here. - `email` boolean, required - `in_app` boolean, required - `codes` string[] — Per-rule code scope. Event-matching rules default to ['_parent_']; silence defaults to ['_any_']. success_rate_drop and recovery take no codes. - `threshold` union — Count or percentage; 'auto' selects anomaly-baseline mode. - number - 'auto' - `sensitivity` 'low' | 'medium' | 'high' — Band width for 'auto' mode. - `fallbackThreshold` number — Static value used while the 'auto' baseline is immature (cold start). - `window` string — Evaluation window, e.g. '15m', '1h', '24h'. - `minSampleSize` integer — success_rate_drop minimum sample size guard. - `quietPeriod` string — silence quiet period, e.g. '12h'. - `digest` NotificationDigestConfig, required — Digest schedule and content configuration. - `enabled` boolean, required - `frequency` 'daily' | 'weekly', required - `dayOfWeek` 0 | 1 | 2 | 3 | 4 | 5 | 6 — Weekly only. 0 = Sunday … 6 = Saturday. - `timeOfDay` string, required — HH:mm - `timezone` string, required — IANA timezone, e.g. 'Europe/Berlin'. - `channels` NotificationChannelSet, required — Delivery channel toggles. New channels added in svc-notification-api inherit here. - `email` boolean, required - `in_app` boolean, required - `includeHealthy` boolean, required — List all integrations vs. only ones with issues. - `skipIfEmpty` boolean, required — Suppress the digest when nothing happened. - `muteUntil` string, date-time, nullable — ISO instant; snooze all non-digest alerts until this time. `null` means not muted. - `integration_type` 'erp' | 'connector' — Type of integration. "erp" is the ERP integration with inbound/outbound use cases. "connector" is for complex proxy integrations with external APIs. - `connector_config` ConnectorConfig — Shared configuration for connector-type integrations - `base_url` string — Base URL for the partner API - `auth` ManagedCallAuth — Authentication configuration for managed call requests - `type` 'oauth2_client_credentials' | 'api_key' | 'bearer' — Authentication type - `token_url` string — OAuth2 token URL. Can be plain text or {{env.key}} reference. - `client_id` string — OAuth2 client ID. Can be plain text or {{env.key}} reference. - `client_secret` string — OAuth2 client secret. Must be an {{env.key}} reference (secret). - `scope` string — OAuth2 scope - `audience` string — OAuth2 audience parameter (e.g. for Auth0, Azure AD). Can be plain text or {{env.key}} reference. - `resource` string — OAuth2 resource parameter (e.g. for Azure AD). Can be plain text or {{env.key}} reference. - `body_params` object — Additional key-value pairs for the OAuth2 token request body. Values can be {{env.key}} references. - `headers` object — Additional headers for the OAuth2 token request. Values can be {{env.key}} references. - `query_params` object — Additional query parameters for the OAuth2 token URL. Values can be {{env.key}} references. - `api_key_header` string — Header name for API key auth (default X-API-Key) - `api_key` string — API key value. Must be an {{env.key}} reference (secret). - `token` string — Bearer token value. Must be an {{env.key}} reference (secret). - `types_versions` object[] — History of generated type package versions - `version` string, required - `package_name` string, required - `generated_at` string, date-time, required - `generated_by` string, required - `status` 'active' | 'deprecated', required - `latest_types_version` string — Latest active types package version - `latest_types_package_name` string — Latest active types package name - `protected` boolean — If true, integration is displayed in read-only mode in the UI to discourage changes - `_manifest` string[] — The manifest IDs associated with this integration - `use_cases` UseCase[], required — All use cases belonging to this integration - union - InboundUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'inbound', required — Use case type - `enabled` boolean, required - `change_description` string — Reason given for the update that produced the current version. Absent when the update supplied none — it is not inherited from the previous version. - `changed_by` string — User ID recorded for the update that produced the current version. Absent when the update had no user context, e.g. an automated sync. - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` InboundIntegrationEventConfiguration — Configuration for inbound use cases (ERP to epilot) - `entities` IntegrationEntity[] — Array of entity configurations for this event - … - `meter_readings` IntegrationMeterReading[] — Array of meter reading configurations for this event - … - OutboundUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'outbound', required — Use case type - `enabled` boolean, required - `change_description` string — Reason given for the update that produced the current version. Absent when the update supplied none — it is not inherited from the previous version. - `changed_by` string — User ID recorded for the update that produced the current version. Absent when the update had no user context, e.g. an automated sync. - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` OutboundIntegrationEventConfiguration — Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings. - `event_catalog_event` string, required — The Event Catalog event name that triggers this outbound flow - `event_filter` string — JSONata boolean predicate over the hydrated event payload. The use case handles the event only when this evaluates truthy; when absent it handles every event of its name, which is the behaviour of every pre-existing configuration. This is where event scoping belongs — narrowing to certain ticket purposes, contract types or channels. Evaluation input is the full hydrated event, so relation nodes such as `ticket` and `contact` are populated. An expression that throws is treated as no match and logged, so one malformed filter cannot block the other use cases subscribed to the same event. - `mappings` OutboundMapping[], required — List of mappings that transform and deliver the event - … - `ack_tracking` 'on' | 'off' — Whether this use case participates in the acknowledgement protocol. `on` (the default, and the behaviour of every pre-existing use case) records an ACK_PENDING on each event and expects the consumer to confirm receipt via `POST /v1/erp/tracking/acknowledgement`; unconfirmed events raise ACK_TIMEOUT after the timeout window. `off` opts the use case out entirely: no tracking row, no ACK_PENDING, no ACK_TIMEOUT. Set it for consumers that never acknowledge — otherwise every event produces a guaranteed timeout warning — and for deliveries that already keep their own durable per-item record, such as `file_proxy`. The tracking row is per-event, not per-use-case, so it is suppressed only when EVERY enabled use case matching the event has opted out. - FileProxyUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'file_proxy', required — Use case type - `enabled` boolean, required - `change_description` string — Reason given for the update that produced the current version. Absent when the update supplied none — it is not inherited from the previous version. - `changed_by` string — User ID recorded for the update that produced the current version. Absent when the update had no user context, e.g. an automated sync. - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` FileProxyUseCaseConfiguration — Configuration for file_proxy use cases. Defines how to authenticate and move files between epilot and an external document system, in either direction (see `direction`). **Download** (`direction: download`, the default) fetches a file from the external system and serves it to a browser. The download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters. The `orgId` is included in the signed URL to establish organization context without requiring authentication. Additional use-case-specific parameters are declared in the `params` array. `response` is REQUIRED for download use cases. **Upload** (`direction: upload`) pushes epilot files to the external system. It is not reachable over the download endpoint; an outbound use case points at it via a `file_proxy` delivery, and this configuration owns everything about what gets sent: `fan_out` decides how many deliveries one event produces, `params_mapping` builds the values, and the `steps` place those values into requests via `{{ params.* }}`. `upload` and `params_mapping` are REQUIRED and `response` MUST be omitted. OpenAPI 3.0 cannot express this conditional requiredness, so it is enforced by the server-side validator, which returns an explicit message naming the offending field. - `direction` 'download' | 'upload' — Direction of file travel. `download` (default) pulls a file from the external system into epilot; `upload` pushes an epilot file out to the external system. Omitted means `download`, so every pre-existing configuration keeps its exact meaning. Note this is the direction of the FILE, not the epilot use-case type — an `upload` file_proxy use case is still a `file_proxy` use case, never an `outbound` one. - `upload` FileProxyUploadConfig — Upload-side settings for a file_proxy use case with `direction: upload`. Everything about WHAT is sent lives on the outbound mapping (see `FileProxyDeliveryConfig`); this object only governs HOW the transfer is bounded and judged. - … - `fan_out` FileProxyFanOutConfig — Splits one event into several independent deliveries. Mirrors the inbound mapping idiom, where an entity's JSONata expression returning an array produces one entity update per element. Made explicit with a toggle here because an upload is also legitimately used without splitting, and because auto-detecting "array means split" would make a single-element result ambiguous. Each resulting delivery is fully independent: its own idempotency record, its own retry schedule, its own monitoring events. A four-item event can therefore end up three-of-four delivered, which is the honest state to report. The split is evaluated ONCE, when the event is enqueued, so item indices — and therefore idempotency keys — stay stable across retries. - … - `params_mapping` string — Upload-only, REQUIRED when `direction` is `upload`. JSONata expression evaluated once per fan-out item, producing the `params` object that step templates read as `{{ params.* }}`. The evaluation root is the hydrated event, so `contact.customer_pin` and `ticket._purpose` are reachable directly, unprefixed. **Everything per-item is a `$`-prefixed JSONata binding**: `$item` (the fan-out element, absent when `fan_out` is disabled), `$file_base64` and `$file` (`{filename, mime_type, size_bytes}`) for the resolved file, plus `$constants`, `$lookups`, `$ack_id`, `$germanDate(iso)` and `$now()`. Writing `item.filename` instead of `$item.filename` yields nothing — it reads a field named `item` on the event, which does not exist. Must evaluate to an object. `constants` are shallow-merged underneath the result, so the expression wins on any key collision. - `lookups` object — Upload-only. Named translation tables resolved BEFORE `params_mapping` runs and bound as `$lookups`, so an expression reads `$lookups.documentType` rather than carrying a conditional chain. Deliberately generic: the next ERP calls the same concept `Belegart`. - `constants` object — Upload-only. Fixed values shallow-merged UNDERNEATH the `params_mapping` result — the expression wins on key collisions, constants only add. Use for the unchanging strings (tenant, sender, channel) that would otherwise be repeated in every expression. - `file_source` string — Upload-only. JSONata returning the attachment-shaped object (`entity_id`, optionally `s3ref`) whose bytes should be fetched for this delivery. The evaluation root is the event; the fan-out element is the `$item` binding, same as in `params_mapping`. Usually unnecessary: when the fan-out item is itself attachment-shaped it is used directly. Supply this only when splitting over something that is not the attachment — for example one delivery per meter reading, each carrying a file referenced from elsewhere in the event. When nothing resolves, no file is fetched and `file_base64` is undefined, which is valid for a fan-out that sends metadata only. - `required_params` string[] — Upload-only. Params that MUST be present after `params_mapping` runs. Any listed name resolving to null or undefined fails the delivery terminally with `REQUIRED_PARAM_MISSING` before a single step executes. This is the generic net behind a lookup's `on_miss: fail`: it catches a required field going missing for any reason, so the external system never receives a body that is silently short a field its API requires. - `secure_proxy` FileProxySecureProxyAttachment - … - `auth` FileProxyAuth - … - `params` FileProxyParam[] — Download-only. Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId). Rejected when `direction` is `upload`. - … - `allowed_origins` string[] — Download-only. Additional origins permitted to call /download for this use case (CORS, exact match). Portal origins are always allowed. Rejected when `direction` is `upload`. - `steps` FileProxyStep[], required — Ordered list of HTTP steps to execute. For `download` these retrieve the file; for `upload` they deliver it, each assembling its own request body from `{{ params.* }}` built by `params_mapping`. - … - `response` FileProxyResponseConfig — How to extract the file from the step results. REQUIRED when `direction` is `download`; rejected when `direction` is `upload` (an upload has no file to extract). - … - `prevent_indirect_serving` boolean — Download-only; rejected when `direction` is `upload`. When `true`, this use case is served via the streaming endpoint: mapped file URLs are built as `/stream/download`, files of any size are streamed inline over HTTP response streaming, and buffered `/download` requests for oversize files are 307-redirected to `/stream`. Files never transit epilot's temporary S3 storage on the streaming path. Defaults to `false` (small files are served directly and large files are transparently served via a temporary S3 redirect). - ManagedCallUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'managed_call', required — Use case type for managed API calls - `enabled` boolean, required - `change_description` string — Reason given for the update that produced the current version. Absent when the update supplied none — it is not inherited from the previous version. - `changed_by` string — User ID recorded for the update that produced the current version. Absent when the update had no user context, e.g. an automated sync. - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` ManagedCallOperationConfig — Configuration for managed_call use cases. Defines a single API operation with JSONata mapping. - `operation` ManagedCallOperation, required — HTTP operation configuration for managed calls - … - `request_mapping` string — JSONata expression for outbound body transformation - `response_mapping` string — JSONata expression for inbound response transformation - `inbound_use_case_slug` string — Slug of the inbound use case to route responses to for async entity processing. When set, the managed call response is queued to the inbound pipeline and processed using the referenced inbound use case's mapping configuration. - `type_annotations` TypeAnnotations — Developer-provided type annotations for a use case's request and response fields - `request` object — Type annotations for request fields, keyed by dot-path (e.g., "vendors[].id" -> "string") - `response` object — Type annotations for response fields - `types_locked` boolean — Whether types have been generated for this use case - SecureProxyUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'secure_proxy', required — Use case type - `enabled` boolean, required - `change_description` string — Reason given for the update that produced the current version. Absent when the update supplied none — it is not inherited from the previous version. - `changed_by` string — User ID recorded for the update that produced the current version. Absent when the update had no user context, e.g. an automated sync. - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` SecureProxyUseCaseConfiguration — Configuration for secure_proxy use cases. Defines how to route requests through a secure VPC. - `vpc_mode` 'static_ip' | 'secure_link', required — VPC routing mode. Read-only after creation. - static_ip: Routes through a VPC with static outbound IP (NAT Gateway) for IP-allowlisted external APIs. - secure_link: Routes through a VPN VPC for accessing private customer networks. - `allowed_domains` string[] — Domain whitelist for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script. Supports exact match (e.g., "api.wemag.com") and wildcard prefix (e.g., "*.wemag.com"). - `allowed_ips` string[] — IP allowlist (CIDR notation) for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script. Required for secure_link mode. All DNS-resolved IPs must match at least one range. Example: ["10.0.1.0/24", "192.168.1.0/24"] ## Other responses - `401` — Unauthorized request - `500` — Internal Server Error --- [API](https://skmtc.net/epilot/apis/integration-toolkit-api.md) · [All operations](https://skmtc.net/epilot/apis/integration-toolkit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/integration-toolkit-api/revisions/68961a011db0/schema)