Skip to main content

Integration Toolkit API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.integrationToolkit.acknowledgeTracking(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/integration-toolkit'

const integrationToolkitClient = getClient()
authorize(integrationToolkitClient, () => '<token>')
const { data } = await integrationToolkitClient.acknowledgeTracking(...)

Operations​

erp

integrations

monitoring

proxy

managed-call

erp-imports

Schemas

acknowledgeTracking​

Acknowledges an ERP tracking record by removing it from the tracking table, requires public authentication

POST /v1/erp/tracking/acknowledgement

const { data } = await client.acknowledgeTracking(
  null,
  {
    ack_id: 'string'
  },
)
Response
{
  "message": "string"
}

triggerErp​

Triggers the ERP integration process

POST /v1/erp/trigger

const { data } = await client.triggerErp(
  null,
  {
    execution_id: 'string',
    org_id: 'string',
    webhook_id: 'string',
    flow_id: 'string',
    created_at: '1970-01-01T00:00:00.000Z',
    action_id: 'string',
    flow_action_id: 'string',
    flow_name: 'string',
    activity_id: 'string',
    entity_id: 'string'
  },
)
Response
{
  "status_code": "string",
  "message": "string",
  "body": {},
  "code": "string",
  "status": "succeeded",
  "start_date": "string",
  "end_date": "string",
  "event_id": "string"
}

processErpUpdatesEventsV3​

Handles updates from ERP systems using integration_id directly. This is the v3 version that removes the unused event_type field and renames object_type to event_name to align with the integration UI n

POST /v3/erp/updates/events

const { data } = await client.processErpUpdatesEventsV3(
  null,
  {
    integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    correlation_id: 'string',
    group_id: 'customer-42',
    interactive: true,
    correlation_complete: true,
    events: [
      {},
      {}
    ]
  },
)
Response
{
  "correlation_id": "string",
  "correlation_close": {
    "outcome": "applied",
    "reasons": ["retry_requested"],
    "message": "string"
  },
  "results": [
    {
      "event_id": "string",
      "status": "success",
      "interactive": true,
      "lane": "interactive",
      "message": "string"
    }
  ]
}

queryErpUpdateEvents​

Waits for the events of one correlation — the long poll behind interactive registration — and returns the correlation's summary.

GET /v3/erp/updates/events

const { data } = await client.queryErpUpdateEvents({
  correlation_id: 'example',
  wait: 1,
  wait_for_entities: ['...'],
  wait_for_use_cases: ['...'],
})
Response
{
  "correlation_id": "string",
  "integration_id": "string",
  "closed": true,
  "closed_at": "1970-01-01T00:00:00.000Z",
  "complete": true,
  "completed_at": "1970-01-01T00:00:00.000Z",
  "events_received": 0,
  "events_done": 0,
  "late_events": 0,
  "first_ingested_at": "1970-01-01T00:00:00.000Z",
  "last_done_at": "1970-01-01T00:00:00.000Z",
  "use_cases": [
    {
      "use_case_slug": "string",
      "received": 0,
      "done": 0,
      "error": 0
    }
  ],
  "entities": [
    {
      "slug": "contact",
      "_id": "string",
      "operation": "created",
      "unique_ids": {
        "reenumber": "4711"
      }
    }
  ],
  "entities_omitted": 0,
  "errors": [
    {
      "code": "string",
      "message": "string",
      "event_id": "string",
      "occurred_at": "1970-01-01T00:00:00.000Z",
      "after_completion": true
    }
  ],
  "errors_total": 0,
  "completion": "requirements_met",
  "undecided_entity_requirements": ["contract[billing_account_number=4711]"]
}

getErpUpdateEvent​

Returns one interactive event's processing record, without waiting.

GET /v3/erp/updates/events/{event_id}

const { data } = await client.getErpUpdateEvent({
  event_id: 'example',
})
Response
{
  "event_id": "string",
  "correlation_id": "string",
  "integration_id": "string",
  "status": "accepted",
  "lane": "interactive",
  "use_case_id": "string",
  "use_case_slug": "string",
  "event_name": "string",
  "ingested_at": "1970-01-01T00:00:00.000Z",
  "mapped_at": "1970-01-01T00:00:00.000Z",
  "done_at": "1970-01-01T00:00:00.000Z",
  "writes_total": 0,
  "writes_done": 0,
  "entities": [
    {
      "slug": "contact",
      "_id": "string",
      "operation": "created",
      "unique_ids": {
        "reenumber": "4711"
      }
    }
  ],
  "entities_omitted": 0,
  "errors": [
    {
      "code": "string",
      "message": "string",
      "event_id": "string",
      "occurred_at": "1970-01-01T00:00:00.000Z",
      "after_completion": true
    }
  ],
  "errors_total": 0
}

listErpUpdateCorrelations​

Lists the organization's interactive correlations, newest first by the time their first event was ingested, with the same summary the correlation wait returns.

GET /v3/erp/updates/correlations

const { data } = await client.listErpUpdateCorrelations({
  integration_id: 'example',
  limit: 1,
  cursor: 'example',
})
Response
{
  "results": [
    {
      "correlation_id": "string",
      "integration_id": "string",
      "closed": true,
      "closed_at": "1970-01-01T00:00:00.000Z",
      "complete": true,
      "completed_at": "1970-01-01T00:00:00.000Z",
      "events_received": 0,
      "events_done": 0,
      "late_events": 0,
      "first_ingested_at": "1970-01-01T00:00:00.000Z",
      "last_done_at": "1970-01-01T00:00:00.000Z",
      "use_cases": [
        {
          "use_case_slug": "string",
          "received": 0,
          "done": 0,
          "error": 0
        }
      ],
      "entities": [
        {
          "slug": "contact",
          "_id": "string",
          "operation": "created",
          "unique_ids": {
            "reenumber": "4711"
          }
        }
      ],
      "entities_omitted": 0,
      "errors": [
        {
          "code": "string",
          "message": "string",
          "event_id": "string",
          "occurred_at": "1970-01-01T00:00:00.000Z",
          "after_completion": true
        }
      ],
      "errors_total": 0
    }
  ],
  "next_cursor": "string",
  "horizon_days": 7
}

simulateMappingV2​

Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data.

POST /v2/erp/updates/mapping_simulation

const { data } = await client.simulateMappingV2(
  null,
  {
    event_configuration: {
      direct: true,
      interactive: 'on_request',
      entities: [
        { /* ... */ }
      ],
      meter_readings: [
        { /* ... */ }
      ]
    },
    format: 'json',
    payload: 'string'
  },
)
Response
{
  "entity_updates": [
    {
      "entity_slug": "string",
      "unique_identifiers": {},
      "attributes": {},
      "pricing": {
        "config": {},
        "data": [
          {}
        ]
      },
      "sharing": {},
      "mode": "upsert"
    }
  ],
  "meter_readings_updates": [
    {
      "meter": {
        "$entity_unique_ids": {}
      },
      "meter_counter": {
        "$entity_unique_ids": {}
      },
      "attributes": {},
      "mode": "upsert"
    }
  ],
  "prune_scope_updates": [
    {
      "entity_slug": "string",
      "scope": {
        "scope_mode": "relations",
        "schema": "string",
        "unique_ids": {},
        "query": {}
      },
      "keep_unique_ids": [
        {}
      ],
      "deletion_mode": "delete"
    }
  ],
  "meter_readings_prune_scope_updates": [
    {
      "meter": {
        "$entity_unique_ids": {}
      },
      "meter_counter": {
        "$entity_unique_ids": {}
      },
      "keep_external_ids": ["string"],
      "source": "string"
    }
  ],
  "warnings": [
    {
      "entity_schema": "string",
      "field": "string",
      "message": "string"
    }
  ]
}

simulateDirect​

Dry run for direct-mode payloads: validates a DirectPayload against a direct: true use case configuration and previews the internal entity and meter reading updates the pipeline would apply — with

POST /v1/erp/updates/direct_simulation

const { data } = await client.simulateDirect(
  null,
  {
    event_configuration: {
      direct: true,
      interactive: 'on_request',
      entities: [
        { /* ... */ }
      ],
      meter_readings: [
        { /* ... */ }
      ]
    },
    payload: 'string'
  },
)
Response
{
  "valid": true,
  "errors": [
    {
      "code": "DIRECT_PAYLOAD_INVALID",
      "message": "string",
      "operation_index": 0
    }
  ],
  "warnings": [
    {
      "entity_schema": "string",
      "field": "string",
      "message": "string"
    }
  ],
  "entity_updates": [
    {
      "entity_slug": "string",
      "unique_identifiers": {},
      "attributes": {},
      "pricing": {
        "config": {},
        "data": [
          {}
        ]
      },
      "sharing": {},
      "mode": "upsert",
      "unique_identifiers_metadata": {}
    }
  ],
  "meter_reading_updates": [
    {
      "meter": {
        "$entity_unique_ids": {}
      },
      "meter_counter": {
        "$entity_unique_ids": {}
      },
      "attributes": {},
      "mode": "upsert",
      "_config": {
        "reading_matching": "external_id"
      }
    }
  ]
}

simulateMapping​

Test mapping configuration by transforming a payload using the provided mapping rules without persisting data.

POST /v1/erp/updates/mapping_simulation

const { data } = await client.simulateMapping(
  null,
  {
    mapping_configuration: {
      version: '1.0',
      mapping: {
        objects: {}
      }
    },
    object_type: 'string',
    format: 'json',
    payload: 'string'
  },
)
Response
{
  "entity_updates": [
    {
      "entity_slug": "string",
      "unique_identifiers": {},
      "attributes": {},
      "pricing": {
        "config": {},
        "data": [
          {}
        ]
      },
      "sharing": {},
      "mode": "upsert"
    }
  ],
  "meter_readings_updates": [
    {
      "meter": {
        "$entity_unique_ids": {}
      },
      "meter_counter": {
        "$entity_unique_ids": {}
      },
      "attributes": {},
      "mode": "upsert"
    }
  ],
  "prune_scope_updates": [
    {
      "entity_slug": "string",
      "scope": {
        "scope_mode": "relations",
        "schema": "string",
        "unique_ids": {},
        "query": {}
      },
      "keep_unique_ids": [
        {}
      ],
      "deletion_mode": "delete"
    }
  ],
  "meter_readings_prune_scope_updates": [
    {
      "meter": {
        "$entity_unique_ids": {}
      },
      "meter_counter": {
        "$entity_unique_ids": {}
      },
      "keep_external_ids": ["string"],
      "source": "string"
    }
  ],
  "warnings": [
    {
      "entity_schema": "string",
      "field": "string",
      "message": "string"
    }
  ]
}

listIntegrations​

Retrieve all integrations for the authenticated organization

GET /v1/integrations

const { data } = await client.listIntegrations()
Response
{
  "integrations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orgId": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "name": "string",
      "description": "string",
      "access_token_ids": ["string"],
      "app_ids": ["string"],
      "environment_config": [],
      "maps": [],
      "settings": {},
      "integration_type": "erp",
      "connector_config": {},
      "protected": true,
      "_manifest": ["string"]
    }
  ]
}

createIntegration​

Create a new integration configuration

POST /v1/integrations

const { data } = await client.createIntegration(
  null,
  {
    name: 'string',
    description: 'string',
    access_token_ids: ['string'],
    app_ids: ['string'],
    environment_config: [
      {
        key: 'string',
        label: 'string',
        type: 'String',
        description: 'string',
        required: false,
        order: 0
      }
    ],
    maps: [
      {
        key: 'string',
        label: 'string',
        description: 'string',
        value: {}
      }
    ],
    settings: {
      autoRefresh: {
        enabled: false,
        freshnessThresholdMinutes: 1
      },
      notifications: {
        enabled: true,
        recipients: [ /* ... */ ],
        defaultChannels: { /* ... */ },
        monitoredUseCases: ['string'],
        monitoredCodes: ['string'],
        rules: [ /* ... */ ],
        digest: { /* ... */ },
        muteUntil: '1970-01-01T00:00:00.000Z'
      }
    },
    integration_type: 'erp',
    connector_config: {
      base_url: 'string',
      auth: {
        type: 'oauth2_client_credentials',
        token_url: 'string',
        client_id: 'string',
        client_secret: 'string',
        scope: 'string',
        audience: 'string',
        resource: 'string',
        body_params: {},
        headers: {},
        query_params: {},
        api_key_header: 'string',
        api_key: 'string',
        token: 'string'
      },
      types_versions: [
        { /* ... */ }
      ],
      latest_types_version: 'string',
      latest_types_package_name: 'string'
    },
    protected: true,
    _manifest: ['string']
  },
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"]
}

getIntegration​

Retrieve a specific integration by its ID

GET /v1/integrations/{integrationId}

const { data } = await client.getIntegration({
  integrationId: 'example',
})
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"]
}

updateIntegration​

Update an existing integration configuration

PUT /v1/integrations/{integrationId}

const { data } = await client.updateIntegration(
  {
    integrationId: 'example',
  },
  {},
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"]
}

deleteIntegration​

Delete an integration and all its use cases

DELETE /v1/integrations/{integrationId}

const { data } = await client.deleteIntegration({
  integrationId: 'example',
})
Response
{
  "message": "string"
}

queryEvents​

Query events for a specific integration

POST /v1/integrations/{integrationId}/events

const { data } = await client.queryEvents(
  {
    integrationId: 'example',
  },
  {
    event_id: 'string',
    event_type: 'CREATE',
    correlation_id: 'string',
    object_type: 'string',
    event_name: 'string',
    use_case_id: 'string',
    limit: 25,
    cursor: {
      event_time: '2025-10-31T12:34:56Z',
      event_id: 'evt_1234567890abcdef'
    }
  },
)
Response
{
  "data": [
    {
      "event_type": "CREATE",
      "object_type": "string",
      "timestamp": "1970-01-01T00:00:00.000Z",
      "format": "json",
      "payload": "string",
      "deduplication_id": "evt-2025-05-01-12345-create-bp",
      "correlation_id": "bp-8f3a2c-7d4e-4b1a-9c2f-1e6d5a4b3c21",
      "use_case_id": "string"
    }
  ],
  "next_cursor": {
    "event_time": "2025-10-31T12:34:56Z",
    "event_id": "evt_1234567890abcdef"
  },
  "has_more": true
}

replayEvents​

Replay one or more events for a specific integration. Events will be re-processed with their original payloads but with a new correlation ID for traceability.

POST /v1/integrations/{integrationId}/events/replay

const { data } = await client.replayEvents(
  {
    integrationId: 'example',
  },
  {
    event_ids: ['string']
  },
)
Response
{
  "replayed": 2,
  "results": [
    {
      "event_id": "string",
      "status": "success",
      "replay_event_id": "string",
      "message": "string"
    }
  ],
  "event_ids": ["string"]
}

listUseCases​

Retrieve all use cases for a specific integration

GET /v1/integrations/{integrationId}/use-cases

const { data } = await client.listUseCases({
  integrationId: 'example',
})
Response
{
  "use_cases": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "type": "inbound",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "configuration": {}
    }
  ]
}

createUseCase​

Create a new use case for an integration

POST /v1/integrations/{integrationId}/use-cases

const { data } = await client.createUseCase(
  {
    integrationId: 'example',
  },
  {
    name: 'string',
    slug: 'string',
    enabled: true,
    type: 'inbound',
    configuration: {
      direct: true,
      interactive: 'on_request',
      entities: [
        { /* ... */ }
      ],
      meter_readings: [
        { /* ... */ }
      ]
    }
  },
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "slug": "string",
  "type": "inbound",
  "enabled": true,
  "change_description": "string",
  "changed_by": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "configuration": {
    "direct": true,
    "interactive": "on_request",
    "entities": [
      {}
    ],
    "meter_readings": [
      {}
    ]
  }
}

getUseCase​

Retrieve a specific use case by its ID

GET /v1/integrations/{integrationId}/use-cases/{useCaseId}

const { data } = await client.getUseCase({
  integrationId: 'example',
  useCaseId: 'example',
})
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "slug": "string",
  "type": "inbound",
  "enabled": true,
  "change_description": "string",
  "changed_by": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "configuration": {
    "direct": true,
    "interactive": "on_request",
    "entities": [
      {}
    ],
    "meter_readings": [
      {}
    ]
  }
}

updateUseCase​

Update an existing use case configuration

PUT /v1/integrations/{integrationId}/use-cases/{useCaseId}

const { data } = await client.updateUseCase(
  {
    integrationId: 'example',
    useCaseId: 'example',
  },
  {
    name: 'string',
    slug: 'string',
    enabled: true,
    change_description: 'string',
    type: 'inbound',
    configuration: {
      direct: true,
      interactive: 'on_request',
      entities: [
        { /* ... */ }
      ],
      meter_readings: [
        { /* ... */ }
      ]
    }
  },
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "slug": "string",
  "type": "inbound",
  "enabled": true,
  "change_description": "string",
  "changed_by": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "configuration": {
    "direct": true,
    "interactive": "on_request",
    "entities": [
      {}
    ],
    "meter_readings": [
      {}
    ]
  }
}

deleteUseCase​

Delete a use case from an integration

DELETE /v1/integrations/{integrationId}/use-cases/{useCaseId}

const { data } = await client.deleteUseCase({
  integrationId: 'example',
  useCaseId: 'example',
})
Response
{
  "message": "string"
}

listUseCaseHistory​

Retrieve historical versions of a use case's configuration. History entries are returned in reverse chronological order (newest first). Use the 'cursor' parameter for pagination to fetch additional en

GET /v1/integrations/{integrationId}/use-cases/{useCaseId}/history

const { data } = await client.listUseCaseHistory({
  integrationId: 'example',
  useCaseId: 'example',
  cursor: 'example',
})
Response
{
  "history": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "history_created_at": "1970-01-01T00:00:00.000Z",
      "type": "inbound",
      "configuration": {}
    }
  ],
  "next_cursor": "string"
}

listDocumentationPages​

Retrieve all documentation pages of an integration, without their markdown content. An integration has at most one general page plus at most one page per use case. The page id is 'general' for the int

GET /v1/integrations/{integrationId}/documentation

const { data } = await client.listDocumentationPages({
  integrationId: 'example',
})
Response
{
  "pages": [
    {
      "id": "general",
      "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "scope": "integration",
      "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "created_by": "string",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "updated_by": "string"
    }
  ]
}

getDocumentationPage​

Retrieve a single documentation page including its markdown content

GET /v1/integrations/{integrationId}/documentation/{docId}

const { data } = await client.getDocumentationPage({
  integrationId: 'example',
  docId: 'example',
})
Response
{
  "id": "general",
  "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "scope": "integration",
  "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "created_by": "string",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "updated_by": "string",
  "content": "string"
}

upsertDocumentationPage​

Create or update the documentation page identified by docId. Upsert semantics enforce the invariant of one general page per integration and one page per use case. For use case pages the use case must

PUT /v1/integrations/{integrationId}/documentation/{docId}

const { data } = await client.upsertDocumentationPage(
  {
    integrationId: 'example',
    docId: 'example',
  },
  {
    title: 'string',
    content: 'string'
  },
)
Response
{
  "id": "general",
  "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "scope": "integration",
  "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "created_by": "string",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "updated_by": "string",
  "content": "string"
}

deleteDocumentationPage​

Delete a documentation page

DELETE /v1/integrations/{integrationId}/documentation/{docId}

const { data } = await client.deleteDocumentationPage({
  integrationId: 'example',
  docId: 'example',
})
Response
{
  "message": "string"
}

listIntegrationsV2​

Retrieve all integrations with embedded use cases for the authenticated organization

GET /v2/integrations

const { data } = await client.listIntegrationsV2()
Response
{
  "integrations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orgId": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "name": "string",
      "description": "string",
      "access_token_ids": ["string"],
      "app_ids": ["string"],
      "environment_config": [],
      "maps": [],
      "settings": {},
      "integration_type": "erp",
      "connector_config": {},
      "protected": true,
      "_manifest": ["string"],
      "use_cases": []
    }
  ]
}

createIntegrationV2​

Create a new integration with embedded use cases.

POST /v2/integrations

const { data } = await client.createIntegrationV2(
  null,
  {
    name: 'string',
    description: 'string',
    access_token_ids: ['string'],
    app_ids: ['string'],
    environment_config: [
      {
        key: 'string',
        label: 'string',
        type: 'String',
        description: 'string',
        required: false,
        order: 0
      }
    ],
    maps: [
      {
        key: 'string',
        label: 'string',
        description: 'string',
        value: {}
      }
    ],
    settings: {
      autoRefresh: {
        enabled: false,
        freshnessThresholdMinutes: 1
      },
      notifications: {
        enabled: true,
        recipients: [ /* ... */ ],
        defaultChannels: { /* ... */ },
        monitoredUseCases: ['string'],
        monitoredCodes: ['string'],
        rules: [ /* ... */ ],
        digest: { /* ... */ },
        muteUntil: '1970-01-01T00:00:00.000Z'
      }
    },
    integration_type: 'erp',
    connector_config: {
      base_url: 'string',
      auth: {
        type: 'oauth2_client_credentials',
        token_url: 'string',
        client_id: 'string',
        client_secret: 'string',
        scope: 'string',
        audience: 'string',
        resource: 'string',
        body_params: {},
        headers: {},
        query_params: {},
        api_key_header: 'string',
        api_key: 'string',
        token: 'string'
      },
      types_versions: [
        { /* ... */ }
      ],
      latest_types_version: 'string',
      latest_types_package_name: 'string'
    },
    protected: true,
    _manifest: ['string'],
    use_cases: [
      {
        id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
        name: 'string',
        slug: 'string',
        enabled: true,
        change_description: 'string',
        type: 'inbound',
        configuration: { /* ... */ }
      }
    ]
  },
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"],
  "use_cases": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "type": "inbound",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "configuration": {}
    }
  ]
}

getIntegrationV2​

Retrieve a specific integration with all its embedded use cases

GET /v2/integrations/{integrationId}

const { data } = await client.getIntegrationV2({
  integrationId: 'example',
})
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"],
  "use_cases": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "type": "inbound",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "configuration": {}
    }
  ]
}

updateIntegrationV2​

Update an existing integration with embedded use cases. The integration must already exist. Use cases are updated declaratively:

  • Use cases in the request with matching IDs are updated
  • Use cases in

PUT /v2/integrations/{integrationId}

const { data } = await client.updateIntegrationV2(
  {
    integrationId: 'example',
  },
  {
    name: 'string',
    description: 'string',
    access_token_ids: ['string'],
    app_ids: ['string'],
    environment_config: [
      {
        key: 'string',
        label: 'string',
        type: 'String',
        description: 'string',
        required: false,
        order: 0
      }
    ],
    maps: [
      {
        key: 'string',
        label: 'string',
        description: 'string',
        value: {}
      }
    ],
    settings: {
      autoRefresh: {
        enabled: false,
        freshnessThresholdMinutes: 1
      },
      notifications: {
        enabled: true,
        recipients: [ /* ... */ ],
        defaultChannels: { /* ... */ },
        monitoredUseCases: ['string'],
        monitoredCodes: ['string'],
        rules: [ /* ... */ ],
        digest: { /* ... */ },
        muteUntil: '1970-01-01T00:00:00.000Z'
      }
    },
    integration_type: 'erp',
    connector_config: {
      base_url: 'string',
      auth: {
        type: 'oauth2_client_credentials',
        token_url: 'string',
        client_id: 'string',
        client_secret: 'string',
        scope: 'string',
        audience: 'string',
        resource: 'string',
        body_params: {},
        headers: {},
        query_params: {},
        api_key_header: 'string',
        api_key: 'string',
        token: 'string'
      },
      types_versions: [
        { /* ... */ }
      ],
      latest_types_version: 'string',
      latest_types_package_name: 'string'
    },
    protected: true,
    _manifest: ['string'],
    use_cases: [
      {
        id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
        name: 'string',
        slug: 'string',
        enabled: true,
        change_description: 'string',
        type: 'inbound',
        configuration: { /* ... */ }
      }
    ]
  },
)
Response
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgId": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z",
  "name": "string",
  "description": "string",
  "access_token_ids": ["string"],
  "app_ids": ["string"],
  "environment_config": [
    {
      "key": "string",
      "label": "string",
      "type": "String",
      "description": "string",
      "required": false,
      "order": 0
    }
  ],
  "maps": [
    {
      "key": "string",
      "label": "string",
      "description": "string",
      "value": {}
    }
  ],
  "settings": {
    "autoRefresh": {
      "enabled": false,
      "freshnessThresholdMinutes": 1
    },
    "notifications": {
      "enabled": true,
      "recipients": [],
      "defaultChannels": {},
      "monitoredUseCases": ["string"],
      "monitoredCodes": ["string"],
      "rules": [],
      "digest": {},
      "muteUntil": "1970-01-01T00:00:00.000Z"
    }
  },
  "integration_type": "erp",
  "connector_config": {
    "base_url": "string",
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "scope": "string",
      "audience": "string",
      "resource": "string",
      "body_params": {},
      "headers": {},
      "query_params": {},
      "api_key_header": "string",
      "api_key": "string",
      "token": "string"
    },
    "types_versions": [
      {}
    ],
    "latest_types_version": "string",
    "latest_types_package_name": "string"
  },
  "protected": true,
  "_manifest": ["string"],
  "use_cases": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "type": "inbound",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "configuration": {}
    }
  ]
}

deleteIntegrationV2​

Delete an integration and all its use cases

DELETE /v2/integrations/{integrationId}

const { data } = await client.deleteIntegrationV2({
  integrationId: 'example',
})
Response
{
  "message": "string"
}

listNotificationHistory​

Returns the cursor-paginated, newest-first notification history for an integration (every real notification decision — both fired and suppressed). Requires the integration:view permission on the int

GET /v2/integrations/{integrationId}/notifications/history

const { data } = await client.listNotificationHistory({
  integrationId: 'example',
  cursor: 'example',
  limit: 1,
  type: 'example',
})
Response
{
  "history": [
    {
      "id": "string",
      "type": "string",
      "state_transition": "string",
      "severity": "error",
      "title": "string",
      "occurred_at": "1970-01-01T00:00:00.000Z",
      "notified": true,
      "suppressed_reason": "muted",
      "recipients": ["string"],
      "context": {},
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

testSendNotification​

Renders and sends ONE representative notification of the requested kind/type to the CALLING USER ONLY (never any other recipient), so an operator can preview how a notification looks. A test send does

POST /v2/integrations/{integrationId}/notifications/test

const { data } = await client.testSendNotification(
  {
    integrationId: 'example',
  },
  {
    kind: 'alert',
    type: 'string',
    channels: ['email']
  },
)

getNotificationStatus​

Returns the live per-rule alert state and (for 'auto' rules) the current hour-of-week baseline band for an integration's notification monitoring. Reflects the latest 5-minute sweep — near-real-time, n

GET /v2/integrations/{integrationId}/notifications/status

const { data } = await client.getNotificationStatus({
  integrationId: 'example',
  include: 'example',
})
Response
{
  "health": "healthy",
  "evaluated_at": "1970-01-01T00:00:00.000Z",
  "rules": [
    {
      "rule_id": "string",
      "state": "ok",
      "last_fired_at": "1970-01-01T00:00:00.000Z",
      "last_cleared_at": "1970-01-01T00:00:00.000Z",
      "last_evaluation": {
        "evaluated_at": "1970-01-01T00:00:00.000Z",
        "observed": 0,
        "threshold": 0,
        "suppressed_reason": "sample_size"
      },
      "baseline": {
        "is_mature": true,
        "computed_at": "1970-01-01T00:00:00.000Z",
        "median": 0,
        "mad": 0,
        "upper": 0,
        "buckets": [
          {
            "dow": 1,
            "hour": 0,
            "median": 0,
            "mad": 0
          }
        ]
      }
    }
  ]
}

getSecureProxyWhitelist​

Returns the current allowed_domains, allowed_ips, and vpc_mode for a secure_proxy use case. Staff-only — gated by internal-auth issuer AND admin-portal Cognito user pool membership. Rejects Login-As t

GET /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist

const { data } = await client.getSecureProxyWhitelist({
  integrationId: 'example',
  useCaseId: 'example',
})
Response
{
  "vpc_mode": "static_ip",
  "allowed_domains": ["string"],
  "allowed_ips": ["string"]
}

updateSecureProxyWhitelist​

Replaces allowed_domains and/or allowed_ips on a secure_proxy use case. At least one of the two fields is required. Validation mirrors the CLI's validateDomainPatterns / validateCidrs. Writes a US

PUT /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist

const { data } = await client.updateSecureProxyWhitelist(
  {
    integrationId: 'example',
    useCaseId: 'example',
  },
  {
    allowed_domains: ['string'],
    allowed_ips: ['string']
  },
)
Response
{
  "vpc_mode": "static_ip",
  "allowed_domains": ["string"],
  "allowed_ips": ["string"]
}

listSecureProxyWhitelistHistory​

Returns the most recent USECASE_HISTORY entries for a secure_proxy use case, in reverse chronological order (newest first). Each entry includes the actor email (changed_by), the ISO-8601 timestamp (

GET /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist/history

const { data } = await client.listSecureProxyWhitelistHistory({
  integrationId: 'example',
  useCaseId: 'example',
  limit: 1,
})
Response
{
  "history": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "enabled": true,
      "change_description": "string",
      "changed_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z",
      "history_created_at": "1970-01-01T00:00:00.000Z",
      "type": "secure_proxy",
      "configuration": {
        "vpc_mode": "static_ip",
        "allowed_domains": ["string"],
        "allowed_ips": ["string"]
      }
    }
  ]
}

setIntegrationAppMapping​

Creates or updates a mapping from an app/component to an integration. This allows ERP updates sent via app_id and component_id to be associated with a specific integration configuration.

PUT /v1/integrations/{integrationId}/app-mapping

const { data } = await client.setIntegrationAppMapping(
  {
    integrationId: 'example',
  },
  {
    app_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    component_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    overwrite: false
  },
)
Response
{
  "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

deleteIntegrationAppMapping​

Removes a mapping from an app/component to an integration.

DELETE /v1/integrations/{integrationId}/app-mapping

const { data } = await client.deleteIntegrationAppMapping(
  {
    integrationId: 'example',
  },
  {
    app_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    component_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
  },
)
Response
{
  "message": "string"
}

getOutboundStatus​

Get the status of all outbound use cases for a specific integration. Returns conflict information when events or webhooks are disabled but the use case is enabled.

GET /v1/integrations/{integrationId}/outbound-status

const { data } = await client.getOutboundStatus({
  integrationId: 'example',
})
Response
{
  "useCases": [
    {
      "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "useCaseEnabled": true,
      "eventCatalogEvent": "contract.created",
      "eventEnabled": true,
      "webhooks": [
        {
          "webhookId": "string",
          "webhookName": "string",
          "enabled": true
        }
      ],
      "status": "ok",
      "conflicts": [
        {
          "type": "event_disabled",
          "webhookId": "string",
          "message": "string"
        }
      ],
      "poll": {
        "queue_depth": 0,
        "oldest_unconsumed_age_seconds": 0,
        "last_poll_at": "1970-01-01T00:00:00.000Z",
        "last_ack_at": "1970-01-01T00:00:00.000Z",
        "blocked": true,
        "dlq_count": 0
      },
      "file_proxy": [
        {
          "mapping_id": "string",
          "use_case_slug": "string",
          "resolved": true,
          "target_use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "target_enabled": true,
          "target_updated_at": "1970-01-01T00:00:00.000Z",
          "unresolved_reason": "not_found"
        }
      ]
    }
  ]
}

getEntitySyncStatus​

Get the inbound ERP sync status of an entity: when each integration last synchronized (checked) the entity against the ERP, and when it last actually changed it. last_synced_at also advances on no-o

GET /v1/integrations/entities/{entityId}/sync-status

const { data } = await client.getEntitySyncStatus({
  entityId: 'example',
  integration_id: 'example',
})
Response
{
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sync_states": [
    {
      "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "entity_slug": "contract",
      "use_case_id": "string",
      "last_synced_at": "1970-01-01T00:00:00.000Z",
      "last_changed_at": "1970-01-01T00:00:00.000Z",
      "last_operation": "create",
      "last_event_id": "string",
      "readings_last_synced_at": "1970-01-01T00:00:00.000Z",
      "readings_last_operation": "upsert",
      "readings_last_event_id": "string"
    }
  ]
}

pollOutboundMessages​

Poll outbound messages for an integration's poll-mode use cases. Takes a lease on the head-of-line batch of the integration's FIFO stream: the returned messages stay invisible to subsequent polls unti

POST /v1/integrations/{integrationId}/outbound/messages/poll

const { data } = await client.pollOutboundMessages(
  {
    integrationId: 'example',
  },
  {
    limit: 10
  },
)
Response
{
  "messages": [
    {
      "id": "string",
      "lease_token": "string",
      "use_case_id": "string",
      "event_name": "string",
      "event_id": "string",
      "group": "string",
      "org_id": "string",
      "payload": {},
      "mapping_version": "3f2a9c1b7d4e8f60",
      "enqueued_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "visibility_timeout_seconds": 0,
  "has_more": true
}

ackOutboundMessages​

Acknowledge polled outbound messages. Acks are validated against the active lease and committed as a prefix-contiguous cursor advance: messages must be acknowledged in stream order. Out-of-order acks

POST /v1/integrations/{integrationId}/outbound/messages/ack

const { data } = await client.ackOutboundMessages(
  {
    integrationId: 'example',
  },
  {
    acks: [
      {
        id: 'string',
        lease_token: 'string'
      }
    ]
  },
)
Response
{
  "results": [
    {
      "id": "string",
      "status": "accepted",
      "reason": "stale_lease"
    }
  ]
}

listOutboundDlqMessages​

List an integration's dead-lettered outbound queue messages (poison_policy enforcement and operator skips move messages here). Operator endpoint — requires the integration:manage grant. Message payl

GET /v1/integrations/{integrationId}/outbound/messages/dlq

const { data } = await client.listOutboundDlqMessages({
  integrationId: 'example',
  limit: 1,
  next_token: 'example',
})
Response
{
  "items": [
    {
      "id": "string",
      "use_case_id": "string",
      "event_name": "string",
      "event_id": "string",
      "enqueued_at": "1970-01-01T00:00:00.000Z",
      "dead_lettered_at": "1970-01-01T00:00:00.000Z",
      "delivery_attempts": 0,
      "reason": "string",
      "mapping_error": "string",
      "mapping_version": "string",
      "expires_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next_token": "string"
}

redriveOutboundDlqMessages​

Redrive selected dead-lettered messages back into the live stream. Operator endpoint — requires the integration:manage grant. A redriven message is re-enqueued at the tail with a new id and sequence

POST /v1/integrations/{integrationId}/outbound/messages/dlq/redrive

const { data } = await client.redriveOutboundDlqMessages(
  {
    integrationId: 'example',
  },
  {
    ids: ['string'],
    reapply_mapping: false
  },
)
Response
{
  "results": [
    {
      "id": "string",
      "status": "redriven",
      "mapping_error": "string"
    }
  ]
}

unblockOutboundStream​

Unblock an integration's outbound stream halted by the block poison policy: skips (dead-letters) the current blocked head message, emitting MSG_DEAD_LETTERED and letting the next message become the

POST /v1/integrations/{integrationId}/outbound/messages/unblock

const { data } = await client.unblockOutboundStream(
  {
    integrationId: 'example',
  },
  {
    reason: 'string'
  },
)
Response
{
  "unblocked": true,
  "dead_lettered_id": "string"
}

simulateOutboundMapping​

Preview a poll delivery's jsonata_expression without saving or enqueueing anything. The expression is checked and evaluated exactly as at enqueue time: the same length, syntax and binding checks, th

POST /v1/integrations/{integrationId}/outbound/mapping-simulation

const { data } = await client.simulateOutboundMapping(
  {
    integrationId: 'example',
  },
  {
    jsonata_expression: '{ "contract_number": contract.contract_number, "status": $mapValue($env.erp.statuses, contract.status) }',
    payload: {},
    event_id: 'string',
    event_catalog_event: 'contract.updated'
  },
)
Response
{
  "valid": true,
  "output": {},
  "error": {
    "code": "syntax_error",
    "message": "string",
    "position": 0
  },
  "mapping_version": "3f2a9c1b7d4e8f60",
  "input": {}
}

queryAccessLogs​

Query API access logs for a specific integration's organization. Returns access token usage analytics filtered by user_id (access token). Supports infinite scroll pagination with cursor-based navigati

POST /v1/integrations/{integrationId}/monitoring/access-logs

const { data } = await client.queryAccessLogs(
  {
    integrationId: 'example',
  },
  {
    token_id: 'api_5ZugdRXasLfWBypHi93Fk',
    service: 'entity',
    method: 'GET',
    path: '/v1/entity',
    status: 200,
    from_date: '2025-01-01T00:00:00Z',
    to_date: '2025-01-31T23:59:59Z',
    limit: 50,
    cursor: {
      timestamp: '1970-01-01T00:00:00.000Z',
      request_id: 'string'
    }
  },
)
Response
{
  "data": [
    {
      "timestamp": "1970-01-01T00:00:00.000Z",
      "environment": "string",
      "service": "string",
      "request_id": "string",
      "method": "string",
      "path": "string",
      "status": 0,
      "response_latency_ms": 0,
      "response_length": 0,
      "token_id": "string",
      "org_id": "string",
      "origin": "string",
      "source_ip": "string"
    }
  ],
  "next_cursor": {
    "timestamp": "1970-01-01T00:00:00.000Z",
    "request_id": "string"
  },
  "has_more": true
}

queryMonitoringEventsV2​

Query monitoring events from the unified erp_monitoring_v2 table. Returns all event types (inbound, outbound, file_proxy, etc.) in a single list. Replaces the separate v1 inbound-events and outbound-e

POST /v2/integrations/{integrationId}/monitoring/events

const { data } = await client.queryMonitoringEventsV2(
  {
    integrationId: 'example',
  },
  {
    use_case_id: 'string',
    use_case_type: 'inbound',
    level: 'success',
    code: 'string',
    event_id: 'string',
    correlation_id: 'string',
    from_date: '2025-01-01T00:00:00Z',
    to_date: '2025-01-31T23:59:59Z',
    limit: 50,
    cursor: {
      created_at: '1970-01-01T00:00:00.000Z',
      id: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    }
  },
)
Response
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_id": "string",
      "integration_id": "string",
      "event_id": "string",
      "correlation_id": "string",
      "use_case_id": "string",
      "use_case_type": "inbound",
      "level": "success",
      "code": "ACK_CONFIRMED",
      "message": "string",
      "detail": {},
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": {
    "created_at": "1970-01-01T00:00:00.000Z",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "has_more": true
}

getMonitoringStatsV2​

Get aggregated statistics from the unified erp_monitoring_v2 table. Returns combined metrics for all event types with optional breakdowns.

POST /v2/integrations/{integrationId}/monitoring/stats

const { data } = await client.getMonitoringStatsV2(
  {
    integrationId: 'example',
  },
  {
    from_date: '2025-01-01T00:00:00Z',
    to_date: '2025-01-31T23:59:59Z',
    correlation_id: 'imp_01M3799K98B6TG7GV7Q2DQT554',
    correlation_ids: ['imp_01M3799K98B6TG7GV7Q2DQT554', 'imp_01M374YPQ0E7ZB0VYJZSK72M4E'],
    use_case_type: 'inbound',
    use_case_types: ['inbound'],
    group_by: 'use_case_id',
    source: 'monitoring'
  },
)
Response
{
  "total_events": 0,
  "success_count": 0,
  "error_count": 0,
  "warning_count": 0,
  "skipped_count": 0,
  "info_count": 0,
  "ack_timeout_count": 0,
  "success_rate": 0,
  "last_error_at": "1970-01-01T00:00:00.000Z",
  "last_event_at": "1970-01-01T00:00:00.000Z",
  "breakdown": [
    {}
  ]
}

getMonitoringTimeSeriesV2​

Get time-series aggregated event counts from the unified erp_monitoring_v2 table. Returns bucketed counts for chart rendering.

POST /v2/integrations/{integrationId}/monitoring/time-series

const { data } = await client.getMonitoringTimeSeriesV2(
  {
    integrationId: 'example',
  },
  {
    from_date: '2025-01-01T00:00:00Z',
    to_date: '2025-01-31T23:59:59Z',
    interval: '5m',
    use_case_type: 'inbound',
    group_by: 'use_case_type'
  },
)
Response
{
  "interval": "5m",
  "from_date": "1970-01-01T00:00:00.000Z",
  "to_date": "1970-01-01T00:00:00.000Z",
  "buckets": [
    {
      "timestamp": "1970-01-01T00:00:00.000Z",
      "success_count": 0,
      "error_count": 0,
      "warning_count": 0,
      "skipped_count": 0,
      "info_count": 0,
      "total_count": 0,
      "breakdown": [
        {
          "use_case_type": "inbound",
          "use_case_id": "string",
          "success_count": 0,
          "error_count": 0,
          "warning_count": 0,
          "skipped_count": 0,
          "info_count": 0,
          "total_count": 0
        }
      ]
    }
  ]
}

getAssociatedMonitoringEvents​

Returns all monitoring events sharing the same event_id, ordered chronologically. Also includes the original inbound event payload from erp_incoming_events if available. Used to display a full event t

GET /v2/integrations/{integrationId}/monitoring/events/{eventId}/associated

const { data } = await client.getAssociatedMonitoringEvents({
  integrationId: 'example',
  eventId: 'example',
})
Response
{
  "monitoring_events": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_id": "string",
      "integration_id": "string",
      "event_id": "string",
      "correlation_id": "string",
      "use_case_id": "string",
      "use_case_type": "inbound",
      "level": "success",
      "code": "ACK_CONFIRMED",
      "message": "string",
      "detail": {},
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "inbound_event": {}
}

ingestExternalMonitoringEvents​

Ingest monitoring spans produced by an EXTERNAL system (e.g. an integration middleware), so the Integration Hub is the central monitoring point and the cross-system event trace spans both the external

POST /v2/integrations/{integrationId}/monitoring/external-events

const { data } = await client.ingestExternalMonitoringEvents(
  {
    integrationId: 'example',
  },
  {
    events: [
      {
        correlation_id: 'string',
        level: 'string',
        use_case_slug: 'string',
        occurred_at: '1970-01-01T00:00:00.000Z',
        message: 'string',
        detail: {}
      }
    ]
  },
)

getMonitoringTraceByCorrelation​

Returns the cross-system event trace for a correlation_id: every monitoring span sharing it — external spans (middleware) plus epilot's own processing spans — ordered chronologically, with a rolled-

GET /v2/integrations/{integrationId}/monitoring/traces/{correlationId}

const { data } = await client.getMonitoringTraceByCorrelation({
  integrationId: 'example',
  correlationId: 'example',
})
Response
{
  "correlation_id": "string",
  "status": "success",
  "started_at": "1970-01-01T00:00:00.000Z",
  "ended_at": "1970-01-01T00:00:00.000Z",
  "span_count": 0,
  "truncated": true,
  "spans": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_id": "string",
      "integration_id": "string",
      "event_id": "string",
      "correlation_id": "string",
      "use_case_id": "string",
      "use_case_type": "inbound",
      "level": "success",
      "code": "ACK_CONFIRMED",
      "message": "string",
      "detail": {},
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "inbound_event": {}
}

getMonitoringRunCompletionV2​

Per-event completion of one or more runs (every monitoring event sharing a correlation_id), each reduced to "how many events have reached a final outcome, and how many are still going". Unlike `getM

POST /v2/integrations/{integrationId}/monitoring/runs/completion

const { data } = await client.getMonitoringRunCompletionV2(
  {
    integrationId: 'example',
  },
  {
    correlation_ids: ['string']
  },
)
Response
{
  "runs": [
    {
      "correlation_id": "string",
      "seen": 0,
      "in_flight": 0,
      "retrying": 0,
      "success": 0,
      "warning": 0,
      "error": 0,
      "info": 0,
      "entries": {
        "total": 0,
        "error": 0,
        "warning": 0,
        "success": 0,
        "info": 0,
        "retry": 0
      },
      "last_activity_at": "1970-01-01T00:00:00.000Z"
    }
  ]
}

listSecureProxies​

Lists all secure_proxy use cases across all integrations for the authenticated organization. Returns minimal data suitable for dropdowns and selection UIs.

GET /v1/integrations/secure-proxies

const { data } = await client.listSecureProxies()
Response
{
  "secure_proxies": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "slug": "string",
      "enabled": true,
      "vpc_mode": "static_ip",
      "allowed_domains": ["string"],
      "allowed_ips": ["string"],
      "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integration_name": "string"
    }
  ]
}

secureProxy​

Routes an HTTP request through a VPC with either static IP egress or VPN secure link access. The VPC mode is determined by the referenced secure_proxy use case configuration. For secure_link mode, the

POST /v1/secure-proxy

const { data } = await client.secureProxy(
  null,
  {
    integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    use_case_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    use_case_slug: 'string',
    url: 'https://example.com/path',
    method: 'GET',
    headers: {},
    body: {},
    response_type: 'json'
  },
)
Response
{
  "status_code": 0,
  "headers": {},
  "body": {}
}

managedCallExecute​

Execute a managed call operation synchronously. The slug in the path acts as the RPC method name. Calls an external partner API with JSONata mapping on both request and response.

POST /v1/managed-call/{slug}/execute

const { data } = await client.managedCallExecute(
  {
    slug: 'example',
  },
  {
    integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    payload: {},
    correlation_id: 'string'
  },
)
Response
{}

generateTypesPreview​

Analyses the JSONata mappings of all managed-call use cases in the integration and returns scaffolded type descriptors. The frontend uses these to show the type editor modal where developers fill in l

POST /v1/integrations/{integrationId}/generate-types-preview

const { data } = await client.generateTypesPreview({
  integrationId: 'example',
})

generateTypes​

Generates a complete TypeScript npm package with typed interfaces for all managed-call use cases. This is a stateless operation that does not persist any changes. Use the commit-types endpoint to lock

POST /v1/integrations/{integrationId}/generate-types

const { data } = await client.generateTypes(
  {
    integrationId: 'example',
  },
  {
    package_name: '@epilot/hems-cleverpv',
    version: '1.0.0',
    description: 'string',
    domain_package: '@epilot/hems',
    domain_map_name: 'HemsUseCaseMap',
    annotations: {}
  },
)
Response
{
  "package_name": "string",
  "version": "string",
  "files": {},
  "warnings": ["string"]
}

commitTypes​

Commits the generated types by locking use case configurations and updating version tracking. Should be called after the user reviews and downloads the generated package.

POST /v1/integrations/{integrationId}/commit-types

const { data } = await client.commitTypes(
  {
    integrationId: 'example',
  },
  {
    package_name: '@epilot/hems-cleverpv',
    version: '1.0.0',
    annotations: {}
  },
)
Response
{
  "committed": true,
  "warnings": ["string"]
}

createErpImport​

Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank cand

POST /v2/erp/imports

const { data } = await client.createErpImport(
  null,
  {
    s3_reference: {
      bucket: 'string',
      key: 'string'
    },
    include_preview: false,
    import_id: 'string'
  },
)
Response
{
  "job": {
    "import_id": "string",
    "org_id": "string",
    "created_by": "string",
    "integration_id": "string",
    "use_case_slug": "string",
    "format": "csv",
    "status": "PENDING",
    "s3_input_ref": {
      "bucket": "string",
      "key": "string"
    },
    "size_bytes": 0,
    "column_count": 0,
    "validation": {
      "total_rows": 0,
      "blocking": 0,
      "warnings": 0,
      "entities": {},
      "entity_details": [
        {
          "mapping_index": 0,
          "entity_schema": "string",
          "business_key": {},
          "variants": 0,
          "versions": 0,
          "condition_attributes": ["grid_area"],
          "version_attribute": "valid_from"
        }
      ],
      "issues": [
        {
          "code": "UNIQUE_ID_COLUMN_MISSING",
          "severity": "warning",
          "columns": [
            {
              "name": "string",
              "entity": "string"
            }
          ],
          "attributes": [
            {
              "name": "string",
              "entity": "string"
            }
          ],
          "lines": [0],
          "subject": "string",
          "row": 0,
          "expected": "number"
        }
      ]
    },
    "progress": {
      "processed_rows": 0,
      "total_rows": 0,
      "events_published": 0
    },
    "error": {
      "code": "VALIDATION_BLOCKED",
      "message": "string"
    },
    "correlation_id": "string",
    "activity_id": "string",
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "preview": {
    "columns": ["string"],
    "rows": [
      ["string"]
    ]
  }
}

listErpImports​

List recent pricing-file import jobs for the org, newest first.

GET /v2/erp/imports

const { data } = await client.listErpImports({
  limit: 1,
  cursor: 'example',
})
Response
{
  "results": [
    {
      "import_id": "string",
      "org_id": "string",
      "created_by": "string",
      "integration_id": "string",
      "use_case_slug": "string",
      "format": "csv",
      "status": "PENDING",
      "s3_input_ref": {
        "bucket": "string",
        "key": "string"
      },
      "size_bytes": 0,
      "column_count": 0,
      "validation": {
        "total_rows": 0,
        "blocking": 0,
        "warnings": 0,
        "entities": {},
        "entity_details": [
          {
            "mapping_index": 0,
            "entity_schema": "string",
            "business_key": {},
            "variants": 0,
            "versions": 0,
            "condition_attributes": ["grid_area"],
            "version_attribute": "valid_from"
          }
        ],
        "issues": [
          {
            "code": "UNIQUE_ID_COLUMN_MISSING",
            "severity": "warning",
            "columns": [
              {
                "name": "string",
                "entity": "string"
              }
            ],
            "attributes": [
              {
                "name": "string",
                "entity": "string"
              }
            ],
            "lines": [0],
            "subject": "string",
            "row": 0,
            "expected": "number"
          }
        ]
      },
      "progress": {
        "processed_rows": 0,
        "total_rows": 0,
        "events_published": 0
      },
      "error": {
        "code": "VALIDATION_BLOCKED",
        "message": "string"
      },
      "correlation_id": "string",
      "activity_id": "string",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

getErpImport​

Get a pricing-file import job (status, counts, result links).

GET /v2/erp/imports/{importId}

const { data } = await client.getErpImport({
  importId: 'example',
})
Response
{
  "import_id": "string",
  "org_id": "string",
  "created_by": "string",
  "integration_id": "string",
  "use_case_slug": "string",
  "format": "csv",
  "status": "PENDING",
  "s3_input_ref": {
    "bucket": "string",
    "key": "string"
  },
  "size_bytes": 0,
  "column_count": 0,
  "validation": {
    "total_rows": 0,
    "blocking": 0,
    "warnings": 0,
    "entities": {},
    "entity_details": [
      {
        "mapping_index": 0,
        "entity_schema": "string",
        "business_key": {},
        "variants": 0,
        "versions": 0,
        "condition_attributes": ["grid_area"],
        "version_attribute": "valid_from"
      }
    ],
    "issues": [
      {
        "code": "UNIQUE_ID_COLUMN_MISSING",
        "severity": "warning",
        "columns": [
          {
            "name": "string",
            "entity": "string"
          }
        ],
        "attributes": [
          {
            "name": "string",
            "entity": "string"
          }
        ],
        "lines": [0],
        "subject": "string",
        "row": 0,
        "expected": "number"
      }
    ]
  },
  "progress": {
    "processed_rows": 0,
    "total_rows": 0,
    "events_published": 0
  },
  "error": {
    "code": "VALIDATION_BLOCKED",
    "message": "string"
  },
  "correlation_id": "string",
  "activity_id": "string",
  "created_at": "1970-01-01T00:00:00.000Z",
  "updated_at": "1970-01-01T00:00:00.000Z"
}

deleteErpImport​

Remove an import and the file it owns. Allowed from any status: an import whose run is still in flight is stopped by the deletion, and rows it already wrote stay written.

DELETE /v2/erp/imports/{importId}

const { data } = await client.deleteErpImport({
  importId: 'example',
})

getErpImportPreview​

The file preview of an existing import: its columns and first data rows, the same sample createErpImport returns with include_preview. Lets a client that opens a job later show its file, and is in

GET /v2/erp/imports/{importId}/preview

const { data } = await client.getErpImportPreview({
  importId: 'example',
})
Response
{
  "columns": ["string"],
  "rows": [
    ["string"]
  ]
}

downloadErpImportFile​

A short-lived presigned URL that downloads the file this import was registered with — the import's own copy, so exactly what :validate and :execute read. The URL serves the file as an attachment u

GET /v2/erp/imports/{importId}/download

const { data } = await client.downloadErpImportFile({
  importId: 'example',
})
Response
{
  "download_url": "https://example.com/path",
  "filename": "string",
  "expires_at": "1970-01-01T00:00:00.000Z"
}

validateErpImport​

Choose the use case to read this file with, and start the validate phase. Callable from PENDING, READY and FAILED — so a wrong choice is corrected by calling this again with a different use case, rath

POST /v2/erp/imports/{importId}:validate

const { data } = await client.validateErpImport(
  {
    importId: 'example',
  },
  {
    integration_id: 'string',
    use_case_slug: 'string'
  },
)

suggestErpImportUseCases​

Rank the org's inbound use cases against this file's columns — the input to the ranked picker ("matches 6 of your 7 columns"). Optional: skip this and call :validate directly when the use case is al

POST /v2/erp/imports/{importId}:suggest-use-cases

const { data } = await client.suggestErpImportUseCases({
  importId: 'example',
})
Response
{
  "file_columns": 0,
  "suggestions": [
    {
      "integration_id": "string",
      "integration_name": "string",
      "use_case_slug": "string",
      "use_case_name": "string",
      "entity_types": 0,
      "matched_columns": 0
    }
  ]
}

executeErpImport​

Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409. The verdict is re-checked against live inputs first: if the mapping or an entity

POST /v2/erp/imports/{importId}:execute

const { data } = await client.executeErpImport(
  {
    importId: 'example',
  },
  {
    ack_warnings: true
  },
)

abortErpImport​

Ask a running import to stop. Valid while the job is VALIDATING or PROCESSING; any other status returns 409. The stop is cooperative: the job passes through CANCELLING and typically reaches CANCELLED

POST /v2/erp/imports/{importId}:abort

const { data } = await client.abortErpImport({
  importId: 'example',
})

Schemas​

S3Reference​

type S3Reference = {
  bucket: string
  key: string
}

CreateErpImportRequest​

Register an already-uploaded file as an import. The use case is chosen later, via :validate — upload and interpretation are separate decisions.

type CreateErpImportRequest = {
  s3_reference: {
    bucket: string
    key: string
  }
  include_preview?: boolean
  import_id?: string
}

ValidateErpImportRequest​

type ValidateErpImportRequest = {
  integration_id: string
  use_case_slug: string
}

ErpImportUseCaseSuggestion​

type ErpImportUseCaseSuggestion = {
  integration_id: string
  integration_name: string
  use_case_slug: string
  use_case_name: string
  entity_types: number
  matched_columns: number
}

SuggestErpImportUseCasesResponse​

type SuggestErpImportUseCasesResponse = {
  file_columns: number
  suggestions: Array<{
    integration_id: string
    integration_name: string
    use_case_slug: string
    use_case_name: string
    entity_types: number
    matched_columns: number
  }>
}

ExecuteErpImportRequest​

Confirmation options. Required only when the verdict carries warnings — a clean import needs no body at all.

type ExecuteErpImportRequest = {
  ack_warnings?: boolean
}

ErpImportIssue​

A problem found during validation, scoped to the file as a whole rather than to individual rows.

code is the translation key and the other fields are its parameters — there is deliberately no message to display. Each code appears at most once (once per expected for VALUE_FORMAT_INVALID), with

type ErpImportIssue = {
  code: "UNIQUE_ID_COLUMN_MISSING" | "MAPPED_COLUMN_MISSING" | "MALFORMED_ROW" | "INVALID_ENCODING" | "EMPTY_FILE" | "TOO_MANY_ROWS" | "BLANK_ROWS_SKIPPED" | "TIER_ROWS_NOT_GROUPED" | "TIER_BANDS_CONFLICT" | "CONDITION_VALUE_MISSING" | "VARIANT_VALUE_CONFLICT" | "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_NOT_IN_SCHEMA" | "IS_CONDITIONAL_NOT_CONSTANT" | "SCHEMA_NOT_CONDITIONABLE" | "SCHEMA_NOT_FOUND" | "SCHEMA_DECLARES_NO_CONDITIONS" | "GROUPING_KEY_NOT_A_COLUMN" | "GROUPING_KEY_IS_SORT_COLUMN" | "CONDITIONAL_TARGET_MODE_UNSUPPORTED" | "UNIQUE_ID_NOT_IN_SCHEMA" | "VALUE_FORMAT_INVALID" | "MAPPING_EXPRESSION_FAILED" | "FROM_ROWS_EXPRESSION_FAILED" | "VALID_FROM_NOT_MAPPED"
  severity: "warning" | "blocking"
  columns?: Array<{
    name: string
    entity?: string
  }>
  attributes?: Array<{
    name: string
    entity?: string
  }>
  lines?: number[]
  subject?: string
  row?: number
  expected?: "number" | "text" | "decimal" | "date"
}

ErpImportValidation​

Validate-phase summary: what the file will create, and whether it may be confirmed. Absent until the validate phase completes. No per-row detail is kept — a rejected file is corrected and imported again.

type ErpImportValidation = {
  total_rows?: number
  blocking: number
  warnings: number
  entities: Record<string, number>
  entity_details?: Array<{
    mapping_index: number
    entity_schema: string
    business_key: Record<string, string>
    variants?: number
    versions?: number
    condition_attributes?: string[]
    version_attribute?: string
  }>
  issues?: Array<{
    code: "UNIQUE_ID_COLUMN_MISSING" | "MAPPED_COLUMN_MISSING" | "MALFORMED_ROW" | "INVALID_ENCODING" | "EMPTY_FILE" | "TOO_MANY_ROWS" | "BLANK_ROWS_SKIPPED" | "TIER_ROWS_NOT_GROUPED" | "TIER_BANDS_CONFLICT" | "CONDITION_VALUE_MISSING" | "VARIANT_VALUE_CONFLICT" | "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_NOT_IN_SCHEMA" | "IS_CONDITIONAL_NOT_CONSTANT" | "SCHEMA_NOT_CONDITIONABLE" | "SCHEMA_NOT_FOUND" | "SCHEMA_DECLARES_NO_CONDITIONS" | "GROUPING_KEY_NOT_A_COLUMN" | "GROUPING_KEY_IS_SORT_COLUMN" | "CONDITIONAL_TARGET_MODE_UNSUPPORTED" | "UNIQUE_ID_NOT_IN_SCHEMA" | "VALUE_FORMAT_INVALID" | "MAPPING_EXPRESSION_FAILED" | "FROM_ROWS_EXPRESSION_FAILED" | "VALID_FROM_NOT_MAPPED"
    severity: "warning" | "blocking"
    columns?: Array<{
      name: { ... }
      entity?: { ... }
    }>
    attributes?: Array<{
      name: { ... }
      entity?: { ... }
    }>
    lines?: number[]
    subject?: string
    row?: number
    expected?: "number" | "text" | "decimal" | "date"
  }>
}

ErpImportEntityDetail​

One entity instance the import will write, attributed to the mapping target that produces it.

type ErpImportEntityDetail = {
  mapping_index: number
  entity_schema: string
  business_key: Record<string, string>
  variants?: number
  versions?: number
  condition_attributes?: string[]
  version_attribute?: string
}

ErpImportProgress​

How far the currently running phase has got. Written at every batch boundary, so it advances during long runs rather than only at the end. total_rows is ABSENT during the validate phase until the file has been read to the end — there is deliberately no counting pass, since that would be a second u

type ErpImportProgress = {
  processed_rows: number
  total_rows?: number
  events_published?: number
}

ErpImportError​

Why the import failed — present if and only if status = FAILED. code is the translation key; for VALIDATION_BLOCKED the specifics are in validation.

type ErpImportError = {
  code: "VALIDATION_BLOCKED" | "FILE_FORMAT_UNSUPPORTED" | "FILE_UNAVAILABLE" | "VALIDATE_TIMEOUT" | "IMPORT_TIMEOUT" | "USE_CASE_NOT_USABLE" | "IMPORT_NO_PROGRESS" | "TIER_ROWS_NOT_GROUPED" | "CHUNK_TOO_LARGE" | "INTERNAL_ERROR"
  message: string
}

ErpImportFilePreview​

Sample of the file's first rows, using the same parser as :validate. Registration refuses a file it cannot read, so a created job always includes this.

type ErpImportFilePreview = {
  columns: string[]
  rows: string[][]
}

ErpImportDownload​

type ErpImportDownload = {
  download_url: string // uri
  filename: string
  expires_at: string // date-time
}

CreateErpImportResponse​

type CreateErpImportResponse = {
  job: {
    import_id: string
    org_id: string
    created_by?: string
    integration_id?: string
    use_case_slug?: string
    format: "csv" | "xlsx"
    status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED"
    s3_input_ref: {
      bucket: { ... }
      key: { ... }
    }
    size_bytes?: number
    column_count?: number
    validation?: {
      total_rows?: { ... }
      blocking: { ... }
      warnings: { ... }
      entities: { ... }
      entity_details?: { ... }
      issues?: { ... }
    }
    progress?: {
      processed_rows: { ... }
      total_rows?: { ... }
      events_published?: { ... }
    }
    error?: {
      code: { ... }
      message: { ... }
    }
    correlation_id?: string
    activity_id?: string
    created_at: string // date-time
    updated_at: string // date-time
  }
  preview?: {
    columns: string[]
    rows: string[][]
  }
}

ErpImportJob​

type ErpImportJob = {
  import_id: string
  org_id: string
  created_by?: string
  integration_id?: string
  use_case_slug?: string
  format: "csv" | "xlsx"
  status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED"
  s3_input_ref: {
    bucket: string
    key: string
  }
  size_bytes?: number
  column_count?: number
  validation?: {
    total_rows?: number
    blocking: number
    warnings: number
    entities: Record<string, number>
    entity_details?: Array<{
      mapping_index: { ... }
      entity_schema: { ... }
      business_key: { ... }
      variants?: { ... }
      versions?: { ... }
      condition_attributes?: { ... }
      version_attribute?: { ... }
    }>
    issues?: Array<{
      code: { ... }
      severity: { ... }
      columns?: { ... }
      attributes?: { ... }
      lines?: { ... }
      subject?: { ... }
      row?: { ... }
      expected?: { ... }
    }>
  }
  progress?: {
    processed_rows: number
    total_rows?: number
    events_published?: number
  }
  error?: {
    code: "VALIDATION_BLOCKED" | "FILE_FORMAT_UNSUPPORTED" | "FILE_UNAVAILABLE" | "VALIDATE_TIMEOUT" | "IMPORT_TIMEOUT" | "USE_CASE_NOT_USABLE" | "IMPORT_NO_PROGRESS" | "TIER_ROWS_NOT_GROUPED" | "CHUNK_TOO_LARGE" | "INTERNAL_ERROR"
    message: string
  }
  correlation_id?: string
  activity_id?: string
  created_at: string // date-time
  updated_at: string // date-time
}

ErpImportList​

type ErpImportList = {
  results: Array<{
    import_id: string
    org_id: string
    created_by?: string
    integration_id?: string
    use_case_slug?: string
    format: "csv" | "xlsx"
    status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED"
    s3_input_ref: {
      bucket: { ... }
      key: { ... }
    }
    size_bytes?: number
    column_count?: number
    validation?: {
      total_rows?: { ... }
      blocking: { ... }
      warnings: { ... }
      entities: { ... }
      entity_details?: { ... }
      issues?: { ... }
    }
    progress?: {
      processed_rows: { ... }
      total_rows?: { ... }
      events_published?: { ... }
    }
    error?: {
      code: { ... }
      message: { ... }
    }
    correlation_id?: string
    activity_id?: string
    created_at: string // date-time
    updated_at: string // date-time
  }>
  next_cursor?: string
}

NotificationHistoryItem​

A single notification-history row (one real notification decision).

type NotificationHistoryItem = {
  id: string
  type: string
  state_transition?: string
  severity: "error" | "warning" | "info"
  title: string
  occurred_at: string // date-time
  notified: boolean
  suppressed_reason?: "muted" | "debounced" | "recipient_opt_out"
  recipients: string[]
  context: Record<string, unknown>
  created_at: string // date-time
}

NotificationHistoryResponse​

type NotificationHistoryResponse = {
  history: Array<{
    id: string
    type: string
    state_transition?: string
    severity: "error" | "warning" | "info"
    title: string
    occurred_at: string // date-time
    notified: boolean
    suppressed_reason?: "muted" | "debounced" | "recipient_opt_out"
    recipients: string[]
    context: Record<string, unknown>
    created_at: string // date-time
  }>
  next_cursor?: string
}

TestNotificationRequest​

type TestNotificationRequest = {
  kind: "alert" | "digest"
  type?: string
  channels?: "email" | "in_app"[]
}

TestNotificationResponse​

type TestNotificationResponse = {
  sent: boolean
  recipient: string
  channels: string[]
  notification_id?: string
}

NotificationStatusResponse​

type NotificationStatusResponse = {
  health: "healthy" | "alerting" | "muted"
  evaluated_at?: string // date-time
  rules: Array<{
    rule_id: string
    state: "ok" | "alerting" | "recovered"
    last_fired_at?: string // date-time
    last_cleared_at?: string // date-time
    last_evaluation?: {
      evaluated_at: { ... }
      observed: { ... }
      threshold?: { ... }
      suppressed_reason?: { ... }
    }
    baseline?: {
      is_mature: { ... }
      computed_at?: { ... }
      median?: { ... }
      mad?: { ... }
      upper?: { ... }
      buckets?: { ... }
    }
  }>
}

NotificationRuleStatus​

type NotificationRuleStatus = {
  rule_id: string
  state: "ok" | "alerting" | "recovered"
  last_fired_at?: string // date-time
  last_cleared_at?: string // date-time
  last_evaluation?: {
    evaluated_at: string // date-time
    observed: number
    threshold?: number
    suppressed_reason?: "sample_size"
  }
  baseline?: {
    is_mature: boolean
    computed_at?: string // date-time
    median?: number
    mad?: number
    upper?: number
    buckets?: Array<{
      dow: { ... }
      hour: { ... }
      median: { ... }
      mad: { ... }
    }>
  }
}

RuleBaselineStatus​

type RuleBaselineStatus = {
  is_mature: boolean
  computed_at?: string // date-time
  median?: number
  mad?: number
  upper?: number
  buckets?: Array<{
    dow: number
    hour: number
    median: number
    mad: number
  }>
}

RuleBaselineBucket​

type RuleBaselineBucket = {
  dow: number
  hour: number
  median: number
  mad: number
}

ErrorResponseBase​

type ErrorResponseBase = {
  code?: string
  message?: string
}

ErpEvent​

type ErpEvent = {
  event_type: "CREATE" | "UPDATE" | "DELETE"
  object_type: string
  timestamp: string // date-time
  format: "json" | "xml"
  payload: string | Record<string, unknown>
  deduplication_id?: string
  correlation_id?: string
  use_case_id?: string
}

ErpUpdatesEventsV2Request​

type ErpUpdatesEventsV2Request = {
  integration_id: string // uuid
  correlation_id?: string
  events: Array<{
    event_type: "CREATE" | "UPDATE" | "DELETE"
    object_type: string
    timestamp: string // date-time
    format: "json" | "xml"
    payload: string | Record<string, unknown>
    deduplication_id?: string
    correlation_id?: string
    use_case_id?: string
  }>
}

ErpEventV3​

type ErpEventV3 = unknown | unknown

ErpUpdatesEventsV3Request​

type ErpUpdatesEventsV3Request = {
  integration_id: string // uuid
  correlation_id?: string
  group_id?: string
  interactive?: boolean
  correlation_complete?: boolean
  events: unknown | unknown[]
}

ErpUpdateProcessedEntity​

An entity an interactive event wrote.

type ErpUpdateProcessedEntity = {
  slug: string
  _id: string
  operation: "created" | "updated" | "deleted" | "unchanged"
  unique_ids: Record<string, string>
}

CorrelationCloseResult​

What became of the request's correlation_complete. Present exactly when the request carried correlation_complete: true; absent otherwise.

type CorrelationCloseResult = {
  outcome: "applied" | "rate_limited" | "ignored"
  reasons?: "retry_requested" | "queue_refused" | "events_under_own_correlation_ids" | "events_duplicate" | "events_not_configured" | "events_not_interactive" | "events_unrecorded" | "rate_limited" | "rate_limit_unavailable" | "other_integration" | "close_failed" | "interactive_unavailable"[]
  message?: string
}

ErpUpdateProcessingError​

A failure nothing will retry.

type ErpUpdateProcessingError = {
  code: string
  message: string
  event_id?: string
  occurred_at: string // date-time
  after_completion?: boolean
}

ErpUpdateEventStatus​

One interactive event's processing record.

type ErpUpdateEventStatus = {
  event_id: string
  correlation_id?: string
  integration_id?: string
  status: "accepted" | "processing" | "done" | "partial" | "error"
  lane: "interactive" | "priority" | "default" | "deferred"
  use_case_id?: string
  use_case_slug?: string
  event_name?: string
  ingested_at: string // date-time
  mapped_at?: string // date-time
  done_at?: string // date-time
  writes_total: number
  writes_done: number
  entities: Array<{
    slug: string
    _id: string
    operation: "created" | "updated" | "deleted" | "unchanged"
    unique_ids: Record<string, string>
  }>
  entities_omitted?: number
  errors: Array<{
    code: string
    message: string
    event_id?: string
    occurred_at: string // date-time
    after_completion?: boolean
  }>
  errors_total: number
}

CorrelationUseCaseCounts​

How many of a correlation's events belong to one use case, and how they ended.

type CorrelationUseCaseCounts = {
  use_case_slug: string
  received: number
  done: number
  error: number
}

CorrelationStatus​

One correlation's summary.

type CorrelationStatus = {
  correlation_id: string
  integration_id?: string
  closed: boolean
  closed_at?: string // date-time
  complete: boolean
  completed_at?: string // date-time
  events_received: number
  events_done: number
  late_events: number
  first_ingested_at?: string // date-time
  last_done_at?: string // date-time
  use_cases: Array<{
    use_case_slug: string
    received: number
    done: number
    error: number
  }>
  entities: Array<{
    slug: string
    _id: string
    operation: "created" | "updated" | "deleted" | "unchanged"
    unique_ids: Record<string, string>
  }>
  entities_omitted?: number
  errors: Array<{
    code: string
    message: string
    event_id?: string
    occurred_at: string // date-time
    after_completion?: boolean
  }>
  errors_total: number
}

CorrelationWaitResult​

type CorrelationWaitResult = {
  correlation_id: string
  integration_id?: string
  closed: boolean
  closed_at?: string // date-time
  complete: boolean
  completed_at?: string // date-time
  events_received: number
  events_done: number
  late_events: number
  first_ingested_at?: string // date-time
  last_done_at?: string // date-time
  use_cases: Array<{
    use_case_slug: string
    received: number
    done: number
    error: number
  }>
  entities: Array<{
    slug: string
    _id: string
    operation: "created" | "updated" | "deleted" | "unchanged"
    unique_ids: Record<string, string>
  }>
  entities_omitted?: number
  errors: Array<{
    code: string
    message: string
    event_id?: string
    occurred_at: string // date-time
    after_completion?: boolean
  }>
  errors_total: number
  completion: "requirements_met" | "complete" | "timeout" | "error"
  undecided_entity_requirements?: string[]
}

CorrelationWaitBadRequest​

type CorrelationWaitBadRequest = {
  message: string
  slug?: string
  rejected_key?: string
  use_case_slug?: string
  allowed_keys?: string[]
}

CorrelationStatusList​

type CorrelationStatusList = {
  results: Array<{
    correlation_id: string
    integration_id?: string
    closed: boolean
    closed_at?: string // date-time
    complete: boolean
    completed_at?: string // date-time
    events_received: number
    events_done: number
    late_events: number
    first_ingested_at?: string // date-time
    last_done_at?: string // date-time
    use_cases: Array<{
      use_case_slug: { ... }
      received: { ... }
      done: { ... }
      error: { ... }
    }>
    entities: Array<{
      slug: { ... }
      _id: { ... }
      operation: { ... }
      unique_ids: { ... }
    }>
    entities_omitted?: number
    errors: Array<{
      code: { ... }
      message: { ... }
      event_id?: { ... }
      occurred_at: { ... }
      after_completion?: { ... }
    }>
    errors_total: number
  }>
  next_cursor: string
  horizon_days: number
}

TriggerErpActionRequest​

type TriggerErpActionRequest = {
  execution_id: string
  org_id: string
  webhook_id: string
  flow_id: string
  created_at: string // date-time
  action_id: string
  flow_action_id: string
  flow_name: string
  activity_id: string
  entity_id: string
}

TriggerWebhookResp​

type TriggerWebhookResp = {
  status_code?: string
  message?: string
  body?: object
  code?: string
  status?: "succeeded" | "failed"
  start_date?: string
  end_date?: string
  event_id?: string
}

IntegrationEditableFields​

type IntegrationEditableFields = {
  name?: string
  description?: string
  access_token_ids?: string[]
  app_ids?: string[]
  environment_config?: Array<{
    key: string
    label: string
    type: "String" | "SecretString"
    description?: string
    required?: boolean
    order?: number
  }>
  maps?: Array<{
    key: string
    label: string
    description?: string
    value: Record<string, unknown>
  }>
  settings?: {
    autoRefresh?: {
      enabled?: { ... }
      freshnessThresholdMinutes?: { ... }
    }
    notifications?: {
      enabled: { ... }
      recipients: { ... }
      defaultChannels: { ... }
      monitoredUseCases?: { ... }
      monitoredCodes?: { ... }
      rules: { ... }
      digest: { ... }
      muteUntil?: { ... }
    }
  }
  integration_type?: "erp" | "connector"
  connector_config?: {
    base_url?: string
    auth?: {
      type?: { ... }
      token_url?: { ... }
      client_id?: { ... }
      client_secret?: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
      api_key_header?: { ... }
      api_key?: { ... }
      token?: { ... }
    }
    types_versions?: Array<{
      version: { ... }
      package_name: { ... }
      generated_at: { ... }
      generated_by: { ... }
      status: { ... }
    }>
    latest_types_version?: string
    latest_types_package_name?: string
  }
  protected?: boolean
  _manifest?: string[]
}

ConnectorConfig​

Shared configuration for connector-type integrations

type ConnectorConfig = {
  base_url?: string
  auth?: {
    type?: "oauth2_client_credentials" | "api_key" | "bearer"
    token_url?: string
    client_id?: string
    client_secret?: string
    scope?: string
    audience?: string
    resource?: string
    body_params?: Record<string, string>
    headers?: Record<string, string>
    query_params?: Record<string, string>
    api_key_header?: string
    api_key?: string
    token?: string
  }
  types_versions?: Array<{
    version: string
    package_name: string
    generated_at: string // date-time
    generated_by: string
    status: "active" | "deprecated"
  }>
  latest_types_version?: string
  latest_types_package_name?: string
}

ManagedCallAuth​

Authentication configuration for managed call requests

type ManagedCallAuth = {
  type?: "oauth2_client_credentials" | "api_key" | "bearer"
  token_url?: string
  client_id?: string
  client_secret?: string
  scope?: string
  audience?: string
  resource?: string
  body_params?: Record<string, string>
  headers?: Record<string, string>
  query_params?: Record<string, string>
  api_key_header?: string
  api_key?: string
  token?: string
}

Integration​

type Integration = {
  id: string // uuid
  orgId: string
  created_at: string // date-time
  updated_at: string // date-time
  name: string
  description?: string
  access_token_ids?: string[]
  app_ids?: string[]
  environment_config?: Array<{
    key: string
    label: string
    type: "String" | "SecretString"
    description?: string
    required?: boolean
    order?: number
  }>
  maps?: Array<{
    key: string
    label: string
    description?: string
    value: Record<string, unknown>
  }>
  settings?: {
    autoRefresh?: {
      enabled?: { ... }
      freshnessThresholdMinutes?: { ... }
    }
    notifications?: {
      enabled: { ... }
      recipients: { ... }
      defaultChannels: { ... }
      monitoredUseCases?: { ... }
      monitoredCodes?: { ... }
      rules: { ... }
      digest: { ... }
      muteUntil?: { ... }
    }
  }
  integration_type?: "erp" | "connector"
  connector_config?: {
    base_url?: string
    auth?: {
      type?: { ... }
      token_url?: { ... }
      client_id?: { ... }
      client_secret?: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
      api_key_header?: { ... }
      api_key?: { ... }
      token?: { ... }
    }
    types_versions?: Array<{
      version: { ... }
      package_name: { ... }
      generated_at: { ... }
      generated_by: { ... }
      status: { ... }
    }>
    latest_types_version?: string
    latest_types_package_name?: string
  }
  protected?: boolean
  _manifest?: string[]
}

CreateIntegrationRequest​

type CreateIntegrationRequest = {
  name: string
  description?: string
  access_token_ids?: string[]
  app_ids?: string[]
  environment_config?: Array<{
    key: string
    label: string
    type: "String" | "SecretString"
    description?: string
    required?: boolean
    order?: number
  }>
  maps?: Array<{
    key: string
    label: string
    description?: string
    value: Record<string, unknown>
  }>
  settings?: {
    autoRefresh?: {
      enabled?: { ... }
      freshnessThresholdMinutes?: { ... }
    }
    notifications?: {
      enabled: { ... }
      recipients: { ... }
      defaultChannels: { ... }
      monitoredUseCases?: { ... }
      monitoredCodes?: { ... }
      rules: { ... }
      digest: { ... }
      muteUntil?: { ... }
    }
  }
  integration_type?: "erp" | "connector"
  connector_config?: {
    base_url?: string
    auth?: {
      type?: { ... }
      token_url?: { ... }
      client_id?: { ... }
      client_secret?: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
      api_key_header?: { ... }
      api_key?: { ... }
      token?: { ... }
    }
    types_versions?: Array<{
      version: { ... }
      package_name: { ... }
      generated_at: { ... }
      generated_by: { ... }
      status: { ... }
    }>
    latest_types_version?: string
    latest_types_package_name?: string
  }
  protected?: boolean
  _manifest?: string[]
}

UpdateIntegrationRequest​

type UpdateIntegrationRequest = {
  name?: string
  description?: string
  access_token_ids?: string[]
  app_ids?: string[]
  environment_config?: Array<{
    key: string
    label: string
    type: "String" | "SecretString"
    description?: string
    required?: boolean
    order?: number
  }>
  maps?: Array<{
    key: string
    label: string
    description?: string
    value: Record<string, unknown>
  }>
  settings?: {
    autoRefresh?: {
      enabled?: { ... }
      freshnessThresholdMinutes?: { ... }
    }
    notifications?: {
      enabled: { ... }
      recipients: { ... }
      defaultChannels: { ... }
      monitoredUseCases?: { ... }
      monitoredCodes?: { ... }
      rules: { ... }
      digest: { ... }
      muteUntil?: { ... }
    }
  }
  integration_type?: "erp" | "connector"
  connector_config?: {
    base_url?: string
    auth?: {
      type?: { ... }
      token_url?: { ... }
      client_id?: { ... }
      client_secret?: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
      api_key_header?: { ... }
      api_key?: { ... }
      token?: { ... }
    }
    types_versions?: Array<{
      version: { ... }
      package_name: { ... }
      generated_at: { ... }
      generated_by: { ... }
      status: { ... }
    }>
    latest_types_version?: string
    latest_types_package_name?: string
  }
  protected?: boolean
  _manifest?: string[]
}

IntegrationMap​

A flat key/value map stored as an Environments API variable of type JSON. Values must be strings, numbers, booleans or null; the serialised map must not exceed 32 KB.

type IntegrationMap = {
  key: string
  label: string
  description?: string
  value: Record<string, unknown>
}

EnvironmentFieldConfig​

type EnvironmentFieldConfig = {
  key: string
  label: string
  type: "String" | "SecretString"
  description?: string
  required?: boolean
  order?: number
}

IntegrationSettings​

Settings for the integration

type IntegrationSettings = {
  autoRefresh?: {
    enabled?: boolean
    freshnessThresholdMinutes?: number
  }
  notifications?: {
    enabled: boolean
    recipients: Array<{
      user_id: { ... }
    }>
    defaultChannels: {
      email: { ... }
      in_app: { ... }
    }
    monitoredUseCases?: string[]
    monitoredCodes?: string[]
    rules: Array<{
      id?: { ... }
      name?: { ... }
      type: { ... }
      enabled: { ... }
      channels?: { ... }
      codes?: { ... }
      threshold?: { ... }
      sensitivity?: { ... }
      fallbackThreshold?: { ... }
      window?: { ... }
      minSampleSize?: { ... }
      quietPeriod?: { ... }
    }>
    digest: {
      enabled: { ... }
      frequency: { ... }
      dayOfWeek?: { ... }
      timeOfDay: { ... }
      timezone: { ... }
      channels: { ... }
      includeHealthy: { ... }
      skipIfEmpty: { ... }
    }
    muteUntil?: string // date-time
  }
}

AutoRefreshSettings​

Auto-refresh settings for keeping integration data fresh

type AutoRefreshSettings = {
  enabled?: boolean
  freshnessThresholdMinutes?: number
}

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.

type IntegrationNotificationConfig = {
  enabled: boolean
  recipients: Array<{
    user_id: string
  }>
  defaultChannels: {
    email: boolean
    in_app: boolean
  }
  monitoredUseCases?: string[]
  monitoredCodes?: string[]
  rules: Array<{
    id?: string
    name?: string
    type: "critical_error" | "error_threshold" | "warning_threshold" | "success_rate_drop" | "recovery" | "silence"
    enabled: boolean
    channels?: {
      email: { ... }
      in_app: { ... }
    }
    codes?: string[]
    threshold?: number | "auto"
    sensitivity?: "low" | "medium" | "high"
    fallbackThreshold?: number
    window?: string
    minSampleSize?: number
    quietPeriod?: string
  }>
  digest: {
    enabled: boolean
    frequency: "daily" | "weekly"
    dayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6
    timeOfDay: string
    timezone: string
    channels: {
      email: { ... }
      in_app: { ... }
    }
    includeHealthy: boolean
    skipIfEmpty: boolean
  }
  muteUntil?: string // date-time
}

NotificationRecipient​

A configured recipient. Only the epilot user_id is stored.

type NotificationRecipient = {
  user_id: string
}

NotificationChannelSet​

Delivery channel toggles. New channels added in svc-notification-api inherit here.

type NotificationChannelSet = {
  email: boolean
  in_app: boolean
}

NotificationRule​

A single notification rule. Only the params relevant to a given type are set. The id is optional on write: the server mints a ULID when omitted and preserves a supplied id verbatim (a stable id keeps a rule's AlertState across config saves).

type NotificationRule = {
  id?: string
  name?: string
  type: "critical_error" | "error_threshold" | "warning_threshold" | "success_rate_drop" | "recovery" | "silence"
  enabled: boolean
  channels?: {
    email: boolean
    in_app: boolean
  }
  codes?: string[]
  threshold?: number | "auto"
  sensitivity?: "low" | "medium" | "high"
  fallbackThreshold?: number
  window?: string
  minSampleSize?: number
  quietPeriod?: string
}

NotificationDigestConfig​

Digest schedule and content configuration.

type NotificationDigestConfig = {
  enabled: boolean
  frequency: "daily" | "weekly"
  dayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  timeOfDay: string
  timezone: string
  channels: {
    email: boolean
    in_app: boolean
  }
  includeHealthy: boolean
  skipIfEmpty: boolean
}

SetIntegrationAppMappingRequest​

type SetIntegrationAppMappingRequest = {
  app_id: string // uuid
  component_id: string // uuid
  overwrite?: boolean
}

DeleteIntegrationAppMappingRequest​

type DeleteIntegrationAppMappingRequest = {
  app_id: string // uuid
  component_id: string // uuid
}

IntegrationAppMapping​

type IntegrationAppMapping = {
  integration_id: string // uuid
}

IntegrationWithUseCases​

type IntegrationWithUseCases = {
  use_cases: Array<{
    id: string // uuid
    integrationId: string // uuid
    name: string
    slug?: string
    type: "inbound"
    enabled: boolean
    change_description?: string
    changed_by?: string
    created_at: string // date-time
    updated_at: string // date-time
    configuration?: {
      direct?: { ... }
      interactive?: { ... }
      entities?: { ... }
      meter_readings?: { ... }
    }
  } | {
    id: string // uuid
    integrationId: string // uuid
    name: string
    slug?: string
    type: "outbound"
    enabled: boolean
    change_description?: string
    changed_by?: string
    created_at: string // date-time
    updated_at: string // date-time
    configuration?: {
      event_catalog_event: { ... }
      event_filter?: { ... }
      mappings: { ... }
      ack_tracking?: { ... }
    }
  } | {
    id: string // uuid
    integrationId: string // uuid
    name: string
    slug?: string
    type: "file_proxy"
    enabled: boolean
    change_description?: string
    changed_by?: string
    created_at: string // date-time
    updated_at: string // date-time
    configuration?: {
      direction?: { ... }
      upload?: { ... }
      fan_out?: { ... }
      secure_proxy?: { ... }
      auth?: { ... }
      params?: { ... }
      allowed_origins?: { ... }
      steps: { ... }
      response?: { ... }
      prevent_indirect_serving?: { ... }
    }
  } | {
    id: string // uuid
    integrationId: string // uuid
    name: string
    slug?: string
    type: "managed_call"
    enabled: boolean
    change_description?: string
    changed_by?: string
    created_at: string // date-time
    updated_at: string // date-time
    configuration?: {
      operation: { ... }
      request_mapping?: { ... }
      response_mapping?: { ... }
      inbound_use_case_slug?: { ... }
    }
    type_annotations?: {
      request?: { ... }
      response?: { ... }
    }
    types_locked?: boolean
  } | {
    id: string // uuid
    integrationId: string // uuid
    name: string
    slug?: string
    type: "secure_proxy"
    enabled: boolean
    change_description?: string
    changed_by?: string
    created_at: string // date-time
    updated_at: string // date-time
    configuration?: {
      vpc_mode: { ... }
      allowed_domains?: { ... }
      allowed_ips?: { ... }
    }
  }>
}

UpsertIntegrationWithUseCasesRequest​

type UpsertIntegrationWithUseCasesRequest = {
  name: string
  description?: string
  access_token_ids?: string[]
  app_ids?: string[]
  environment_config?: Array<{
    key: string
    label: string
    type: "String" | "SecretString"
    description?: string
    required?: boolean
    order?: number
  }>
  maps?: Array<{
    key: string
    label: string
    description?: string
    value: Record<string, unknown>
  }>
  settings?: {
    autoRefresh?: {
      enabled?: { ... }
      freshnessThresholdMinutes?: { ... }
    }
    notifications?: {
      enabled: { ... }
      recipients: { ... }
      defaultChannels: { ... }
      monitoredUseCases?: { ... }
      monitoredCodes?: { ... }
      rules: { ... }
      digest: { ... }
      muteUntil?: { ... }
    }
  }
  integration_type?: "erp" | "connector"
  connector_config?: {
    base_url?: string
    auth?: {
      type?: { ... }
      token_url?: { ... }
      client_id?: { ... }
      client_secret?: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
      api_key_header?: { ... }
      api_key?: { ... }
      token?: { ... }
    }
    types_versions?: Array<{
      version: { ... }
      package_name: { ... }
      generated_at: { ... }
      generated_by: { ... }
      status: { ... }
    }>
    latest_types_version?: string
    latest_types_package_name?: string
  }
  protected?: boolean
  _manifest?: string[]
  use_cases?: Array<{
    id?: string // uuid
    name: string
    slug?: string
    enabled: boolean
    change_description?: string
    type: "inbound"
    configuration?: {
      direct?: { ... }
      interactive?: { ... }
      entities?: { ... }
      meter_readings?: { ... }
    }
  } | {
    id?: string // uuid
    name: string
    slug?: string
    enabled: boolean
    change_description?: string
    type: "outbound"
    configuration?: {
      event_catalog_event: { ... }
      event_filter?: { ... }
      mappings: { ... }
      ack_tracking?: { ... }
    }
  } | {
    id?: string // uuid
    name: string
    slug?: string
    enabled: boolean
    change_description?: string
    type: "file_proxy"
    configuration?: {
      direction?: { ... }
  // ...
}

InboundIntegrationEventConfiguration​

Configuration for inbound use cases (ERP to epilot)

type InboundIntegrationEventConfiguration = {
  direct?: boolean
  interactive?: "disabled" | "on_request" | "always"
  entities?: Array<{
    entity_schema: string
    unique_ids: string[]
    jsonataExpression?: string
    enabled?: boolean | string
    mode?: "upsert" | "delete" | "purge" | "upsert-prune-scope-purge" | "upsert-prune-scope-delete"
    scope?: {
      scope_mode: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      query?: { ... }
    }
    fields?: Array<{
      attribute: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
      _type?: { ... }
      enabled?: { ... }
      relations?: { ... }
      relation_refs?: { ... }
      file_proxy_url?: { ... }
      portal_ref?: { ... }
      env_var_ref?: { ... }
    }>
    conditional?: {
      from_rows: { ... }
    }
    sharing?: {
      partners: { ... }
    }
  }>
  meter_readings?: Array<{
    jsonataExpression?: string
    reading_matching?: "external_id" | "strict-date"
    mode?: "upsert" | "delete" | "upsert-prune-scope"
    scope?: {
      source?: { ... }
    }
    meter: {
      unique_ids: { ... }
    }
    meter_counter?: {
      unique_ids: { ... }
    }
    fields: Array<{
      attribute: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
      _type?: { ... }
      enabled?: { ... }
      relations?: { ... }
      relation_refs?: { ... }
      file_proxy_url?: { ... }
      portal_ref?: { ... }
      env_var_ref?: { ... }
    }>
  }>
}

OutboundIntegrationEventConfiguration​

Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.

type OutboundIntegrationEventConfiguration = {
  event_catalog_event: string
  event_filter?: string
  mappings: Array<{
    id?: string // uuid
    name: string
    jsonata_expression?: string
    enabled: boolean
    delivery: {
      type: { ... }
      webhook_id: { ... }
      webhook_name?: { ... }
      webhook_url?: { ... }
    } | {
      type: { ... }
      retention_days?: { ... }
      poison_policy?: { ... }
      max_delivery_attempts?: { ... }
    } | {
      type: { ... }
      use_case_slug: { ... }
    }
    created_at?: string // date-time
    updated_at?: string // date-time
  }>
  ack_tracking?: "on" | "off"
}

IntegrationEntity​

type IntegrationEntity = {
  entity_schema: string
  unique_ids: string[]
  jsonataExpression?: string
  enabled?: boolean | string
  mode?: "upsert" | "delete" | "purge" | "upsert-prune-scope-purge" | "upsert-prune-scope-delete"
  scope?: {
    scope_mode: "relations" | "query"
    schema?: string
    unique_ids?: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
    query?: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
  }
  fields?: Array<{
    attribute: string
    field?: string
    jsonataExpression?: string
    constant?: unknown
    _type?: "email" | "phone"
    enabled?: boolean | string
    relations?: {
      operation: { ... }
      items?: { ... }
      jsonataExpression?: { ... }
    }
    relation_refs?: {
      operation: { ... }
      items?: { ... }
      jsonataExpression?: { ... }
    }
    file_proxy_url?: {
      use_case_slug: { ... }
      params?: { ... }
    } | {
      use_case_id: { ... }
      params?: { ... }
    }
    portal_ref?: {
      filter?: { ... }
      select?: { ... }
      return?: { ... }
    } | {
      filter?: { ... }
      select?: { ... }
      return: { ... }
      jsonataExpression: { ... }
    }
    env_var_ref?: {
      key: { ... }
      default?: { ... }
      return?: { ... }
    } | {
      key: { ... }
      default?: { ... }
      return: { ... }
      jsonataExpression: { ... }
    }
  }>
  conditional?: {
    from_rows: Array<{
      attribute: { ... }
      sort_by: { ... }
      item: { ... }
    }>
  }
  sharing?: {
    partners: Array<{
      partner_org_id: { ... }
      enabled?: { ... }
    }>
  }
}

IntegrationEntitySharing​

Keeps the mapped entity's sharing with partner organizations in sync. After the entity is written, it is shared with every listed partner whose enabled is true and unshared from every listed partner whose enabled is false. Changes are computed against the entity's current _acl, so a repeated e

type IntegrationEntitySharing = {
  partners: Array<{
    partner_org_id: string
    enabled?: boolean | string
  }>
}

IntegrationEntitySharingPartner​

type IntegrationEntitySharingPartner = {
  partner_org_id: string
  enabled?: boolean | string
}

IntegrationEntityConditional​

Conditional Pricing extras for this target, used when it writes a conditional entity (a Product, Price or Coupon carrying context-dependent variants). The conditions themselves are declared on the entity schema, not here.

type IntegrationEntityConditional = {
  from_rows: Array<{
    attribute: string
    sort_by: {
      field: { ... }
    } | {
      constant: { ... }
    } | {
      jsonataExpression: { ... }
    }
    item: Record<string, {
      field: { ... }
    } | {
      constant: { ... }
    } | {
      jsonataExpression: { ... }
    }>
  }>
}

IntegrationEntityFromRows​

Build one array attribute from the rows of one variant-version, ordered by a column. A commodity file carries one row per consumption band, while a variant-version holds exactly one tiers array.

type IntegrationEntityFromRows = {
  attribute: string
  sort_by: {
    field: string
  } | {
    constant: unknown
  } | {
    jsonataExpression: string
  }
  item: Record<string, {
    field: string
  } | {
    constant: unknown
  } | {
    jsonataExpression: string
  }>
}

MappedFieldValue​

One mapped value. Exactly one of field, constant or jsonataExpression must be set — the same three forms IntegrationEntityField accepts.

type MappedFieldValue = {
  field: string
} | {
  constant: unknown
} | {
  jsonataExpression: string
}

IntegrationMeterReading​

type IntegrationMeterReading = {
  jsonataExpression?: string
  reading_matching?: "external_id" | "strict-date"
  mode?: "upsert" | "delete" | "upsert-prune-scope"
  scope?: {
    source?: string
  }
  meter: {
    unique_ids: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
  }
  meter_counter?: {
    unique_ids: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
  }
  fields: Array<{
    attribute: string
    field?: string
    jsonataExpression?: string
    constant?: unknown
    _type?: "email" | "phone"
    enabled?: boolean | string
    relations?: {
      operation: { ... }
      items?: { ... }
      jsonataExpression?: { ... }
    }
    relation_refs?: {
      operation: { ... }
      items?: { ... }
      jsonataExpression?: { ... }
    }
    file_proxy_url?: {
      use_case_slug: { ... }
      params?: { ... }
    } | {
      use_case_id: { ... }
      params?: { ... }
    }
    portal_ref?: {
      filter?: { ... }
      select?: { ... }
      return?: { ... }
    } | {
      filter?: { ... }
      select?: { ... }
      return: { ... }
      jsonataExpression: { ... }
    }
    env_var_ref?: {
      key: { ... }
      default?: { ... }
      return?: { ... }
    } | {
      key: { ... }
      default?: { ... }
      return: { ... }
      jsonataExpression: { ... }
    }
  }>
}

PruneScopeConfig​

Scope configuration for upsert-prune-scope modes. Defines how to find entities that should be pruned if not in the upsert payload. The scope is resolved against the original event payload (not individual array items).

type PruneScopeConfig = {
  scope_mode: "relations" | "query"
  schema?: string
  unique_ids?: Array<{
    attribute: string
    _type?: "email" | "phone"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }>
  query?: Array<{
    attribute: string
    _type?: "email" | "phone"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }>
}

MeterReadingPruneScopeConfig​

Scope configuration for meter reading upsert-prune-scope mode. The scope is all readings for the same meter + counter.

type MeterReadingPruneScopeConfig = {
  source?: string
}

MeterUniqueIdsConfig​

type MeterUniqueIdsConfig = {
  unique_ids: Array<{
    attribute: string
    _type?: "email" | "phone"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }>
}

IntegrationEntityField​

type IntegrationEntityField = {
  attribute: string
  field?: string
  jsonataExpression?: string
  constant?: unknown
  _type?: "email" | "phone"
  enabled?: boolean | string
  relations?: {
    operation: "_set" | "_append" | "_append_all"
    items?: Array<{
      entity_schema: { ... }
      _tags?: { ... }
      unique_ids: { ... }
      required?: { ... }
    }>
    jsonataExpression?: string
  }
  relation_refs?: {
    operation: "_set" | "_append" | "_append_all"
    items?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      path: { ... }
      value: { ... }
    }>
    jsonataExpression?: string
  }
  file_proxy_url?: {
    use_case_slug: string
    params?: Record<string, {
      field: { ... }
    } | {
      constant: { ... }
    } | {
      jsonataExpression: { ... }
    }>
  } | {
    use_case_id: string
    params?: Record<string, {
      field: { ... }
    } | {
      constant: { ... }
    } | {
      jsonataExpression: { ... }
    }>
  }
  portal_ref?: {
    filter?: {
      origin?: { ... }
      enabled?: { ... }
      is_dummy?: { ... }
      is_epilot_domain?: { ... }
      name?: { ... }
      domain?: { ... }
    }
    select?: "single" | "all"
    return?: "portal_id" | "origin" | "domain" | "name"
  } | {
    filter?: {
      origin?: { ... }
      enabled?: { ... }
      is_dummy?: { ... }
      is_epilot_domain?: { ... }
      name?: { ... }
      domain?: { ... }
    }
    select?: "single" | "all"
    return: "jsonata"
    jsonataExpression: string
  }
  env_var_ref?: {
    key: string
    default?: string
    return?: "value"
  } | {
    key: string
    default?: string
    return: "jsonata"
    jsonataExpression: string
  }
}

FileProxyUrlParam​

Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set.

type FileProxyUrlParam = {
  field: string
} | {
  constant: unknown
} | {
  jsonataExpression: string
}

FileProxyUrlParams​

Custom query parameters. Keys become URL param names, values resolved from payload.

type FileProxyUrlParams = Record<string, {
  field: string
} | {
  constant: unknown
} | {
  jsonataExpression: string
}>

FileProxyUrlConfig​

Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.

type FileProxyUrlConfig = {
  use_case_slug: string
  params?: Record<string, {
    field: string
  } | {
    constant: unknown
  } | {
    jsonataExpression: string
  }>
} | {
  use_case_id: string
  params?: Record<string, {
    field: string
  } | {
    constant: unknown
  } | {
    jsonataExpression: string
  }>
}

PortalOrigin​

Origin/type of an epilot portal configuration.

type PortalOrigin = "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"

PortalRefFilter​

Filter applied to the org's portal configurations before selection. All filters default to "match any" except enabled (default true) and is_dummy (default false). Set enabled or is_dummy to null to opt out of the default.

type PortalRefFilter = {
  origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[]
  enabled?: boolean
  is_dummy?: boolean
  is_epilot_domain?: boolean
  name?: string
  domain?: string
}

PortalRefConfig​

Resolves to a property of one of the calling organization's epilot portal configurations at runtime, replacing hard-coded environment-specific portal UUIDs in inbound mappings. Matched portals are sorted ascending by (_created_at, portal_id); portals without _created_at sort first (treated as ol

type PortalRefConfig = {
  filter?: {
    origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[]
    enabled?: boolean
    is_dummy?: boolean
    is_epilot_domain?: boolean
    name?: string
    domain?: string
  }
  select?: "single" | "all"
  return?: "portal_id" | "origin" | "domain" | "name"
} | {
  filter?: {
    origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[]
    enabled?: boolean
    is_dummy?: boolean
    is_epilot_domain?: boolean
    name?: string
    domain?: string
  }
  select?: "single" | "all"
  return: "jsonata"
  jsonataExpression: string
}

EnvVarRefConfig​

Resolves to an org-scoped environment variable from the epilot environments-api service at runtime, replacing hard-coded environment-specific values (URLs, prefixes, identifiers) in inbound mappings. Secrets (SecretString values) are never exposed; the runtime treats both "missing key" and "secret

type EnvVarRefConfig = {
  key: string
  default?: string
  return?: "value"
} | {
  key: string
  default?: string
  return: "jsonata"
  jsonataExpression: string
}

EmbeddedUseCaseRequest​

type EmbeddedUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
} | {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
} | {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
  // ...
}

EmbeddedUseCaseRequestBase​

type EmbeddedUseCaseRequestBase = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
}

EmbeddedInboundUseCaseRequest​

type EmbeddedInboundUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
}

EmbeddedOutboundUseCaseRequest​

type EmbeddedOutboundUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
}

EmbeddedFileProxyUseCaseRequest​

type EmbeddedFileProxyUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
    }
    prevent_indirect_serving?: boolean
  }
}

EmbeddedManagedCallUseCaseRequest​

type EmbeddedManagedCallUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "managed_call"
  configuration?: {
    operation: {
      method: { ... }
      path: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    request_mapping?: string
    response_mapping?: string
    inbound_use_case_slug?: string
  }
}

EmbeddedSecureProxyUseCaseRequest​

type EmbeddedSecureProxyUseCaseRequest = {
  id?: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  type: "secure_proxy"
  configuration?: {
    vpc_mode: "static_ip" | "secure_link"
    allowed_domains?: string[]
    allowed_ips?: string[]
  }
}

UseCaseBase​

type UseCaseBase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
}

InboundUseCase​

type InboundUseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "inbound"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
}

OutboundUseCase​

type OutboundUseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "outbound"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
}

FileProxyUseCase​

type FileProxyUseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "file_proxy"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
    }
    prevent_indirect_serving?: boolean
  }
}

ManagedCallUseCase​

type ManagedCallUseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "managed_call"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    operation: {
      method: { ... }
      path: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    request_mapping?: string
    response_mapping?: string
    inbound_use_case_slug?: string
  }
  type_annotations?: {
    request?: Record<string, string>
    response?: Record<string, string>
  }
  types_locked?: boolean
}

SecureProxyUseCase​

type SecureProxyUseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "secure_proxy"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    vpc_mode: "static_ip" | "secure_link"
    allowed_domains?: string[]
    allowed_ips?: string[]
  }
}

UseCase​

type UseCase = {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "inbound"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
} | {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "outbound"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
} | {
  id: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  type: "file_proxy"
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
  // ...
}

CreateUseCaseRequest​

type CreateUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
} | {
  name: string
  slug: string
  enabled: boolean
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
} | {
  name: string
  slug: string
  enabled: boolean
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
  // ...
}

CreateUseCaseRequestBase​

type CreateUseCaseRequestBase = {
  name: string
  slug: string
  enabled: boolean
}

CreateInboundUseCaseRequest​

type CreateInboundUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
}

CreateOutboundUseCaseRequest​

type CreateOutboundUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
}

CreateFileProxyUseCaseRequest​

type CreateFileProxyUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
    }
    prevent_indirect_serving?: boolean
  }
}

CreateManagedCallUseCaseRequest​

type CreateManagedCallUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "managed_call"
  configuration?: {
    operation: {
      method: { ... }
      path: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    request_mapping?: string
    response_mapping?: string
    inbound_use_case_slug?: string
  }
}

CreateSecureProxyUseCaseRequest​

type CreateSecureProxyUseCaseRequest = {
  name: string
  slug: string
  enabled: boolean
  type: "secure_proxy"
  configuration?: {
    vpc_mode: "static_ip" | "secure_link"
    allowed_domains?: string[]
    allowed_ips?: string[]
  }
}

UpdateUseCaseRequest​

type UpdateUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
} | {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
} | {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
  // ...
}

UpdateUseCaseRequestBase​

type UpdateUseCaseRequestBase = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
}

UpdateInboundUseCaseRequest​

type UpdateInboundUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
}

UpdateOutboundUseCaseRequest​

type UpdateOutboundUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
}

UpdateFileProxyUseCaseRequest​

type UpdateFileProxyUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
    }
    prevent_indirect_serving?: boolean
  }
}

UpdateManagedCallUseCaseRequest​

type UpdateManagedCallUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "managed_call"
  configuration?: {
    operation: {
      method: { ... }
      path: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    request_mapping?: string
    response_mapping?: string
    inbound_use_case_slug?: string
  }
  type_annotations?: {
    request?: Record<string, string>
    response?: Record<string, string>
  }
}

UpdateSecureProxyUseCaseRequest​

type UpdateSecureProxyUseCaseRequest = {
  name?: string
  slug?: string
  enabled?: boolean
  change_description?: string
  type?: "secure_proxy"
  configuration?: {
    vpc_mode: "static_ip" | "secure_link"
    allowed_domains?: string[]
    allowed_ips?: string[]
  }
}

UseCaseHistoryEntry​

type UseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
} | {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
} | {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
  // ...
}

UseCaseHistoryEntryBase​

type UseCaseHistoryEntryBase = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
}

InboundUseCaseHistoryEntry​

type InboundUseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "inbound"
  configuration?: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
}

OutboundUseCaseHistoryEntry​

type OutboundUseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "outbound"
  configuration?: {
    event_catalog_event: string
    event_filter?: string
    mappings: Array<{
      id?: { ... }
      name: { ... }
      jsonata_expression?: { ... }
      enabled: { ... }
      delivery: { ... }
      created_at?: { ... }
      updated_at?: { ... }
    }>
    ack_tracking?: "on" | "off"
  }
}

FileProxyUseCaseHistoryEntry​

type FileProxyUseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "file_proxy"
  configuration?: {
    direction?: "download" | "upload"
    upload?: {
      max_total_bytes?: { ... }
      max_file_bytes?: { ... }
      max_delivery_attempts?: { ... }
    }
    fan_out?: {
      enabled: { ... }
    }
    secure_proxy?: {
      use_case_slug: { ... }
    }
    auth?: {
      type: { ... }
      token_url: { ... }
      client_id: { ... }
      client_secret: { ... }
      scope?: { ... }
      audience?: { ... }
      resource?: { ... }
      username?: { ... }
      password?: { ... }
      body_params?: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    params?: Array<{
      name: { ... }
      required: { ... }
      description?: { ... }
    }>
    allowed_origins?: string // uri[]
    steps: Array<{
      url: { ... }
      method: { ... }
      headers?: { ... }
      body_jsonata?: { ... }
      enabled?: { ... }
      body?: { ... }
      response_type: { ... }
    }>
    response?: {
      body: { ... }
      encoding: { ... }
      filename?: { ... }
      content_type?: { ... }
    }
    prevent_indirect_serving?: boolean
  }
}

ManagedCallUseCaseHistoryEntry​

type ManagedCallUseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "managed_call"
  configuration?: {
    operation: {
      method: { ... }
      path: { ... }
      headers?: { ... }
      query_params?: { ... }
    }
    request_mapping?: string
    response_mapping?: string
    inbound_use_case_slug?: string
  }
  type_annotations?: {
    request?: Record<string, string>
    response?: Record<string, string>
  }
  types_locked?: boolean
}

SecureProxyUseCaseHistoryEntry​

type SecureProxyUseCaseHistoryEntry = {
  id: string // uuid
  useCaseId: string // uuid
  integrationId: string // uuid
  name: string
  slug?: string
  enabled: boolean
  change_description?: string
  changed_by?: string
  created_at: string // date-time
  updated_at: string // date-time
  history_created_at: string // date-time
  type: "secure_proxy"
  configuration?: {
    vpc_mode: "static_ip" | "secure_link"
    allowed_domains?: string[]
    allowed_ips?: string[]
  }
}

SecureProxyUseCaseConfiguration​

Configuration for secure_proxy use cases. Defines how to route requests through a secure VPC.

type SecureProxyUseCaseConfiguration = {
  vpc_mode: "static_ip" | "secure_link"
  allowed_domains?: string[]
  allowed_ips?: string[]
}

SecureProxyWhitelist​

Current whitelist state for a secure_proxy use case. vpc_mode is read-only context so the UI can show the user what mode the pool is in.

type SecureProxyWhitelist = {
  vpc_mode: "static_ip" | "secure_link"
  allowed_domains: string[]
  allowed_ips: string[]
}

SecureProxyWhitelistUpdate​

Partial update for a secure_proxy whitelist. At least one of allowed_domains or allowed_ips must be provided.

Per-field semantics:

  • omitted — the field is not modified; the stored value is preserved.
  • non-empty array — the stored value is replaced with the supplied list.
  • **emp
type SecureProxyWhitelistUpdate = {
  allowed_domains?: string[]
  allowed_ips?: string[]
}

SecureProxySummary​

type SecureProxySummary = {
  id: string // uuid
  name: string
  slug?: string
  enabled: boolean
  vpc_mode: "static_ip" | "secure_link"
  allowed_domains?: string[]
  allowed_ips?: string[]
  integration_id: string // uuid
  integration_name: string
}

SecureProxyRequest​

type SecureProxyRequest = {
  integration_id: string // uuid
  use_case_id?: string // uuid
  use_case_slug?: string
  url: string // uri
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
  headers?: Record<string, string>
  body?: unknown
  response_type?: "json" | "binary"
}

SecureProxyResponse​

type SecureProxyResponse = {
  status_code?: number
  headers?: Record<string, string>
  body?: unknown
}

SecureProxyUpstreamError​

Error payload returned when epilot could not obtain an HTTP response from the proxied target. The failure is epilot-generated (HTTP 502) but the cause is usually remote-side; code/reason make that attributable.

type SecureProxyUpstreamError = {
  message: "Upstream network error" | "Upstream error"
  code?: string
  reason?: string
}

ManagedCallOperationConfig​

Configuration for managed_call use cases. Defines a single API operation with JSONata mapping.

type ManagedCallOperationConfig = {
  operation: {
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
    path: string
    headers?: Record<string, string>
    query_params?: Record<string, string>
  }
  request_mapping?: string
  response_mapping?: string
  inbound_use_case_slug?: string
}

ManagedCallOperation​

HTTP operation configuration for managed calls

type ManagedCallOperation = {
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
  path: string
  headers?: Record<string, string>
  query_params?: Record<string, string>
}

ManagedCallExecuteRequest​

type ManagedCallExecuteRequest = {
  integration_id: string // uuid
  payload?: Record<string, unknown>
  correlation_id?: string
}

ManagedCallExecuteResponse​

The response from a managed call execution. On success, returns the JSONata-mapped response data directly (no wrapper). The shape is entirely defined by your response_mapping JSONata expression. If no response_mapping is configured, returns the raw external API response. Check the X-Inbound-Event-Id

type ManagedCallExecuteResponse = unknown

ManagedCallErrorResponse​

type ManagedCallErrorResponse = {
  error: {
    code: string
    message: string
    details?: Record<string, unknown>
  }
}

TypeAnnotations​

Developer-provided type annotations for a use case's request and response fields

type TypeAnnotations = {
  request?: Record<string, string>
  response?: Record<string, string>
}

TypeDescriptor​

Describes the inferred type shape of a JSONata expression

type TypeDescriptor = {
  kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union"
  properties?: Record<string, { ... }>
  items?: { ... }
  source?: string
  variants?: { ... }[]
}

UseCaseTypePreview​

Scaffolded type descriptors for a single use case

type UseCaseTypePreview = {
  slug: string
  name?: string
  request_shape: {
    kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union"
    properties?: Record<string, { ... }>
    items?: { ... }
    source?: string
    variants?: { ... }[]
  }
  response_shape: {
    kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union"
    properties?: Record<string, { ... }>
    items?: { ... }
    source?: string
    variants?: { ... }[]
  }
  existing_annotations?: {
    request?: Record<string, string>
    response?: Record<string, string>
  }
}

GenerateTypesPreviewResponse​

type GenerateTypesPreviewResponse = {
  integration_name?: string
  use_cases: Array<{
    slug: string
    name?: string
    request_shape: {
      kind: { ... }
      properties?: { ... }
      items?: { ... }
      source?: { ... }
      variants?: { ... }
    }
    response_shape: {
      kind: { ... }
      properties?: { ... }
      items?: { ... }
      source?: { ... }
      variants?: { ... }
    }
    existing_annotations?: {
      request?: { ... }
      response?: { ... }
    }
  }>
  previous_version?: string
  suggested_version?: string
  suggested_bump?: "major" | "minor"
  detected_changes?: Array<{
    slug: string
    field: string
    type: "breaking" | "non-breaking"
    description: string
  }>
}

GenerateTypesRequest​

type GenerateTypesRequest = {
  package_name: string
  version: string
  description?: string
  domain_package?: string
  domain_map_name?: string
  annotations?: Record<string, {
    request?: Record<string, string>
    response?: Record<string, string>
  }>
}

GenerateTypesResponse​

type GenerateTypesResponse = {
  package_name: string
  version: string
  files: Record<string, string>
  warnings?: string[]
}

CommitTypesRequest​

type CommitTypesRequest = {
  package_name: string
  version: string
  annotations?: Record<string, {
    request?: Record<string, string>
    response?: Record<string, string>
  }>
}

CommitTypesResponse​

type CommitTypesResponse = {
  committed: boolean
  warnings?: string[]
}

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 downloa

type FileProxyUseCaseConfiguration = {
  direction?: "download" | "upload"
  upload?: {
    max_total_bytes?: number
    max_file_bytes?: number
    max_delivery_attempts?: number
  }
  fan_out?: {
    enabled: boolean
  }
  secure_proxy?: {
    use_case_slug: string
  }
  auth?: {
    type: "oauth2_client_credentials" | "oauth2_password"
    token_url: string
    client_id: string
    client_secret: string
    scope?: string
    audience?: string
    resource?: string
    username?: string
    password?: string
    body_params?: Record<string, string>
    headers?: Record<string, string>
    query_params?: Record<string, string>
  }
  params?: Array<{
    name: string
    required: boolean
    description?: string
  }>
  allowed_origins?: string // uri[]
  steps: Array<{
    url: string
    method: "GET" | "POST" | "PUT" | "PATCH"
    headers?: Record<string, string>
    body_jsonata?: string
    enabled?: string
    body?: string
    response_type: "json" | "binary"
  }>
  response?: {
    body: string
    encoding: "base64" | "binary"
    filename?: string
    content_type?: string
  }
  prevent_indirect_serving?: boolean
}

FileProxySecureProxyAttachment​

type FileProxySecureProxyAttachment = {
  use_case_slug: string
}

FileProxyAuth​

type FileProxyAuth = {
  type: "oauth2_client_credentials" | "oauth2_password"
  token_url: string
  client_id: string
  client_secret: string
  scope?: string
  audience?: string
  resource?: string
  username?: string
  password?: string
  body_params?: Record<string, string>
  headers?: Record<string, string>
  query_params?: Record<string, string>
}

FileProxyParam​

type FileProxyParam = {
  name: string
  required: boolean
  description?: string
}

FileProxyStep​

type FileProxyStep = {
  url: string
  method: "GET" | "POST" | "PUT" | "PATCH"
  headers?: Record<string, string>
  body_jsonata?: string
  enabled?: string
  body?: string
  response_type: "json" | "binary"
}

FileProxyFanOutConfig​

Whether one event produces one delivery per file, or a single delivery carrying all of them. The split is always over the event's event_attachments — there is no expression to write, because an upload only ever runs on events that declare that field.

Each resulting delivery is fully independent: 

type FileProxyFanOutConfig = {
  enabled: boolean
}

FileProxyUploadConfig​

Upload-side settings for a file_proxy use case with direction: upload. The surrounding file_proxy configuration owns WHAT and HOW to send: fan_out, auth, and the steps with their body_jsonata. This nested object governs upload-specific limits and how the final external response is judged. The

type FileProxyUploadConfig = {
  max_total_bytes?: number
  max_file_bytes?: number
  max_delivery_attempts?: number
}

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).

type FileProxyResponseConfig = {
  body: string
  encoding: "base64" | "binary"
  filename?: string
  content_type?: string
}

MappingSimulationRequest​

type MappingSimulationRequest = {
  mapping_configuration: {
    version?: "1.0"
    mapping: {
      objects: { ... }
    }
  } | {
    version: "2.0"
    mapping: {
      events: { ... }
    }
  }
  object_type: string
  format: "json" | "xml"
  payload: string | Record<string, unknown>
}

MappingSimulationV2Request​

Request for v2 mapping simulation. Uses the same configuration format stored in integration use case resources, making it easier to test configurations before saving them.

type MappingSimulationV2Request = {
  event_configuration: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
  format: "json" | "xml"
  payload: string | Record<string, unknown>
}

MappingSimulationResponse​

type MappingSimulationResponse = {
  entity_updates: Array<{
    entity_slug: string
    unique_identifiers: Record<string, unknown>
    attributes: Record<string, unknown>
    pricing?: {
      config: { ... }
      data: { ... }
    }
    sharing?: Record<string, unknown>
    mode: "upsert" | "delete" | "purge"
  }>
  meter_readings_updates?: Array<{
    meter: {
      $entity_unique_ids: { ... }
    }
    meter_counter?: {
      $entity_unique_ids?: { ... }
    }
    attributes: Record<string, unknown>
    mode: "upsert" | "delete"
  }>
  prune_scope_updates?: Array<{
    entity_slug: string
    scope: {
      scope_mode: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      query?: { ... }
    }
    keep_unique_ids: Record<string, unknown>[]
    deletion_mode: "delete" | "purge"
  }>
  meter_readings_prune_scope_updates?: Array<{
    meter: {
      $entity_unique_ids: { ... }
    }
    meter_counter?: {
      $entity_unique_ids?: { ... }
    }
    keep_external_ids: string[]
    source?: string
  }>
  warnings?: Array<{
    entity_schema: string
    field: string
    message: string
  }>
}

MappingSimulationWarning​

type MappingSimulationWarning = {
  entity_schema: string
  field: string
  message: string
}

DirectPayload​

The payload of an ERP event routed to a direct: true use case: a versioned envelope of pre-mapped operations that skip the mapping engine. Sent as the payload of an ErpEventV3 - either as a JSON object or as a JSON string (format must be json; XML is rejected for direct use cases).

The sc

type DirectPayload = {
  version: string
  operations: Array<{
    type?: "entity"
    entity_slug: string
    unique_ids: Record<string, string | number>
    unique_id_types?: Record<string, "email" | "phone">
    mode?: "upsert" | "delete" | "purge"
    attributes?: Record<string, {
      $relation: { ... }
    } | {
      $relation_ref: { ... }
    } | unknown>
  } | {
    type: "meter_reading"
    meter: {
      unique_ids: { ... }
    }
    counter?: {
      unique_ids: { ... }
    }
    mode?: "upsert" | "delete"
    reading_matching?: "external_id" | "strict-date"
    attributes: {
      external_id: { ... }
      timestamp: { ... }
      source: { ... }
      value: { ... }
    }
  }>
}

DirectEntityOperation​

A single pre-mapped entity operation: upserts, soft-deletes, or purges one entity, identified by its unique ids. Produces the same internal update as a mapped-mode entity configuration, so create-vs-update resolution, relation resolution, ordering, and monitoring behave identically.

type DirectEntityOperation = {
  type?: "entity"
  entity_slug: string
  unique_ids: Record<string, string | number>
  unique_id_types?: Record<string, "email" | "phone">
  mode?: "upsert" | "delete" | "purge"
  attributes?: Record<string, {
    $relation: Array<{
      entity_id?: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      unique_id_types?: { ... }
      tags?: { ... }
    }> | {
      _set?: { ... }
      _append?: { ... }
      _append_all?: { ... }
    }
  } | {
    $relation_ref: Array<{
      schema: { ... }
      unique_ids: { ... }
      unique_id_types?: { ... }
      path: { ... }
      value: { ... }
    }> | {
      _set?: { ... }
      _append?: { ... }
      _append_all?: { ... }
    }
  } | unknown>
}

DirectMeterReadingOperation​

A single pre-mapped meter reading operation: upserts or deletes one reading on a meter (and optionally a specific counter), identified by their unique ids. Produces the same internal update as a mapped-mode meter reading configuration.

type DirectMeterReadingOperation = {
  type: "meter_reading"
  meter: {
    unique_ids: Record<string, string | number>
  }
  counter?: {
    unique_ids: Record<string, string | number>
  }
  mode?: "upsert" | "delete"
  reading_matching?: "external_id" | "strict-date"
  attributes: {
    external_id: string | number
    timestamp: string
    source: "ECP" | "ERP" | "360" | "journey-submission"
    value: number | string
  }
}

DirectRelationValue​

An entity attribute value that establishes relations to other entities. Written on any attribute inside a direct entity operation's attributes.

Two forms are accepted: a bare array of items (shorthand for _set, i.e. replace), or an object with EXACTLY ONE of the operations _set (replace), `_a

type DirectRelationValue = {
  $relation: Array<{
    entity_id?: string
    schema?: string
    unique_ids?: Record<string, string | number>
    unique_id_types?: Record<string, "email" | "phone">
    tags?: string[]
  }> | {
    _set?: Array<{
      entity_id?: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      unique_id_types?: { ... }
      tags?: { ... }
    }>
    _append?: Array<{
      entity_id?: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      unique_id_types?: { ... }
      tags?: { ... }
    }>
    _append_all?: Array<{
      entity_id?: { ... }
      schema?: { ... }
      unique_ids?: { ... }
      unique_id_types?: { ... }
      tags?: { ... }
    }>
  }
}

DirectRelationItem​

One relation target: either an already-resolved reference (entity_id), or a lookup by unique ids (schema + unique_ids, resolved by the pipeline like any other unique-id lookup, including stub creation and retry when the target does not exist yet). The two forms are mutually exclusive. Use `_id

type DirectRelationItem = {
  entity_id?: string
  schema?: string
  unique_ids?: Record<string, string | number>
  unique_id_types?: Record<string, "email" | "phone">
  tags?: string[]
}

DirectRelationRefValue​

An entity attribute value that references an ITEM INSIDE a repeatable attribute of another entity - for example one address out of a contact's address list. The target entity is looked up by unique ids, then the item at path matching value is referenced (creating it when missing).

The same op

type DirectRelationRefValue = {
  $relation_ref: Array<{
    schema: string
    unique_ids: Record<string, string | number>
    unique_id_types?: Record<string, "email" | "phone">
    path: string
    value: unknown
  }> | {
    _set?: Array<{
      schema: { ... }
      unique_ids: { ... }
      unique_id_types?: { ... }
      path: { ... }
      value: { ... }
    }>
    _append?: Array<{
      schema: { ... }
      unique_ids: { ... }
      unique_id_types?: { ... }
      path: { ... }
      value: { ... }
    }>
    _append_all?: Array<{
      schema: { ... }
      unique_ids: { ... }
      unique_id_types?: { ... }
      path: { ... }
      value: { ... }
    }>
  }
}

DirectRelationRefItem​

One relation-ref target - the entity to look up, and the repeatable item to reference on it.

type DirectRelationRefItem = {
  schema: string
  unique_ids: Record<string, string | number>
  unique_id_types?: Record<string, "email" | "phone">
  path: string
  value: unknown
}

DirectSimulationRequest​

Request for a direct-mode dry run: the direct: true use case configuration to test against, and the payload to validate and translate.

type DirectSimulationRequest = {
  event_configuration: {
    direct?: boolean
    interactive?: "disabled" | "on_request" | "always"
    entities?: Array<{
      entity_schema: { ... }
      unique_ids: { ... }
      jsonataExpression?: { ... }
      enabled?: { ... }
      mode?: { ... }
      scope?: { ... }
      fields?: { ... }
      conditional?: { ... }
      sharing?: { ... }
    }>
    meter_readings?: Array<{
      jsonataExpression?: { ... }
      reading_matching?: { ... }
      mode?: { ... }
      scope?: { ... }
      meter: { ... }
      meter_counter?: { ... }
      fields: { ... }
    }>
  }
  payload: string | {
    version: string
    operations: Array<{
      type?: { ... }
      entity_slug: { ... }
      unique_ids: { ... }
      unique_id_types?: { ... }
      mode?: { ... }
      attributes?: { ... }
    } | {
      type: { ... }
      meter: { ... }
      counter?: { ... }
      mode?: { ... }
      reading_matching?: { ... }
      attributes: { ... }
    }>
  }
}

DirectSimulationResponse​

Result of a direct-mode dry run. valid: false responses list EVERY violation found across all operations in errors. valid: true responses preview the internal updates the pipeline would apply, plus non-blocking warnings.

type DirectSimulationResponse = {
  valid: boolean
  errors: Array<{
    code: "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DIRECT_ENTITY_NOT_ALLOWED"
    message: string
    operation_index?: number
  }>
  warnings?: Array<{
    entity_schema: string
    field: string
    message: string
  }>
  entity_updates?: Array<{
    entity_slug: string
    unique_identifiers: Record<string, unknown>
    attributes: Record<string, unknown>
    pricing?: {
      config: { ... }
      data: { ... }
    }
    sharing?: Record<string, unknown>
    mode: "upsert" | "delete" | "purge"
    unique_identifiers_metadata?: Record<string, {
      fieldType?: { ... }
      index?: { ... }
    }>
  }>
  meter_reading_updates?: Array<{
    meter: {
      $entity_unique_ids: { ... }
    }
    meter_counter?: {
      $entity_unique_ids?: { ... }
    }
    attributes: Record<string, unknown>
    mode: "upsert" | "delete"
    _config?: {
      reading_matching?: { ... }
    }
  }>
}

DirectSimulationError​

One validation error found during a direct-mode dry run.

type DirectSimulationError = {
  code: "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DIRECT_ENTITY_NOT_ALLOWED"
  message: string
  operation_index?: number
}

EntityUpdate​

type EntityUpdate = {
  entity_slug: string
  unique_identifiers: Record<string, unknown>
  attributes: Record<string, unknown>
  pricing?: {
    config: Record<string, unknown>
    data: Record<string, unknown>[]
  }
  sharing?: Record<string, unknown>
  mode: "upsert" | "delete" | "purge"
}

MeterReadingUpdate​

type MeterReadingUpdate = {
  meter: {
    $entity_unique_ids: Record<string, unknown>
  }
  meter_counter?: {
    $entity_unique_ids?: Record<string, unknown>
  }
  attributes: Record<string, unknown>
  mode: "upsert" | "delete"
}

EntityPruneScopeUpdate​

A resolved entity prune scope. At runtime, entities of entity_slug found within scope whose unique identifiers are not listed in keep_unique_ids are removed using deletion_mode.

type EntityPruneScopeUpdate = {
  entity_slug: string
  scope: {
    scope_mode: "relations" | "query"
    schema?: string
    unique_ids?: Record<string, unknown>
    query?: Record<string, unknown>
  }
  keep_unique_ids: Record<string, unknown>[]
  deletion_mode: "delete" | "purge"
}

MeterReadingPruneScopeUpdate​

A resolved meter reading prune scope. At runtime, readings of the given meter (+ counter) whose external ids are not listed in keep_external_ids are deleted.

type MeterReadingPruneScopeUpdate = {
  meter: {
    $entity_unique_ids: Record<string, unknown>
  }
  meter_counter?: {
    $entity_unique_ids?: Record<string, unknown>
  }
  keep_external_ids: string[]
  source?: string
}

IntegrationConfigurationV1​

type IntegrationConfigurationV1 = {
  version?: "1.0"
  mapping: {
    objects: Record<string, {
      unique_ids: { ... }
      fields: { ... }
    }>
  }
}

IntegrationObjectV1​

type IntegrationObjectV1 = {
  unique_ids: Record<string, string[] | Record<string, string>>
  fields: Array<{
    entity: string
    attribute: string
    field?: string
    jsonataExpression?: string
  }>
}

IntegrationFieldV1​

type IntegrationFieldV1 = {
  entity: string
  attribute: string
  field?: string
  jsonataExpression?: string
}

IntegrationConfigurationV2​

type IntegrationConfigurationV2 = {
  version: "2.0"
  mapping: {
    events: Record<string, {
      direct?: { ... }
      interactive?: { ... }
      entities?: { ... }
      meter_readings?: { ... }
    }>
  }
}

OutboundMapping​

A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (the raw event payload, or its JSONata transformation when the mapping carries one), or handed to a file_proxy 

type OutboundMapping = {
  id?: string // uuid
  name: string
  jsonata_expression?: string
  enabled: boolean
  delivery: {
    type: "webhook"
    webhook_id: string
    webhook_name?: string
    webhook_url?: string
  } | {
    type: "poll"
    retention_days?: number
    poison_policy?: "dead_letter" | "block"
    max_delivery_attempts?: number
  } | {
    type: "file_proxy"
    use_case_slug: string
  }
  created_at?: string // date-time
  updated_at?: string // date-time
}

DeliveryConfig​

Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload, or its JSONata transformation when the mapping carries a jsonata_express

type DeliveryConfig = {
  type: "webhook"
  webhook_id: string
  webhook_name?: string
  webhook_url?: string
} | {
  type: "poll"
  retention_days?: number
  poison_policy?: "dead_letter" | "block"
  max_delivery_attempts?: number
} | {
  type: "file_proxy"
  use_case_slug: string
}

WebhookDeliveryConfig​

Push delivery of the transformed event to a webhook via svc-webhooks

type WebhookDeliveryConfig = {
  type: "webhook"
  webhook_id: string
  webhook_name?: string
  webhook_url?: string
}

PollDeliveryConfig​

Pull-based queue delivery. Consumers fetch and acknowledge items via the poll API. When the mapping carries a jsonata_expression, it is evaluated once at enqueue time against the standardized event-catalog event (with $env/$mapValue/$mapKey bindings) and its output — a JSON object — is the d

type PollDeliveryConfig = {
  type: "poll"
  retention_days?: number
  poison_policy?: "dead_letter" | "block"
  max_delivery_attempts?: number
}

FileProxyDeliveryConfig​

Push delivery to an external document system through a file_proxy use case.

A pure pointer, deliberately. The outbound use case decides WHEN to deliver — its event name plus event_filter — and the referenced file_proxy use case decides WHAT and HOW: which items to fan out over (fan_out), wh

type FileProxyDeliveryConfig = {
  type: "file_proxy"
  use_case_slug: string
}

EntitySyncStatusResponse​

type EntitySyncStatusResponse = {
  entity_id: string // uuid
  sync_states: Array<{
    entity_id: string // uuid
    integration_id: string // uuid
    entity_slug: string
    use_case_id?: string
    last_synced_at?: string // date-time
    last_changed_at?: string // date-time
    last_operation?: "create" | "patch" | "delete" | "no-op"
    last_event_id?: string
    readings_last_synced_at?: string // date-time
    readings_last_operation?: "upsert" | "delete"
    readings_last_event_id?: string
  }>
}

EntitySyncState​

Inbound sync state of one entity for one integration. Carries two independent groups: the entity-level fields (last_synced_at, …) and, on meter/meter_counter entities, the readings-level fields (readings_last_synced_at, …). Either group can be present alone — a meter whose readings sync via the 

type EntitySyncState = {
  entity_id: string // uuid
  integration_id: string // uuid
  entity_slug: string
  use_case_id?: string
  last_synced_at?: string // date-time
  last_changed_at?: string // date-time
  last_operation?: "create" | "patch" | "delete" | "no-op"
  last_event_id?: string
  readings_last_synced_at?: string // date-time
  readings_last_operation?: "upsert" | "delete"
  readings_last_event_id?: string
}

OutboundStatusResponse​

type OutboundStatusResponse = {
  useCases: Array<{
    useCaseId: string // uuid
    name: string
    useCaseEnabled: boolean
    eventCatalogEvent?: string
    eventEnabled?: boolean
    webhooks?: Array<{
      webhookId: { ... }
      webhookName?: { ... }
      enabled?: { ... }
    }>
    status: "ok" | "conflict" | "disabled"
    conflicts?: Array<{
      type: { ... }
      webhookId?: { ... }
      message: { ... }
    }>
    poll?: {
      queue_depth: { ... }
      oldest_unconsumed_age_seconds: { ... }
      last_poll_at: { ... }
      last_ack_at: { ... }
      blocked: { ... }
      dlq_count: { ... }
    }
    file_proxy?: Array<{
      mapping_id: { ... }
      use_case_slug: { ... }
      resolved: { ... }
      target_use_case_id?: { ... }
      target_enabled?: { ... }
      target_updated_at?: { ... }
      unresolved_reason?: { ... }
    }>
  }>
}

OutboundUseCaseStatus​

type OutboundUseCaseStatus = {
  useCaseId: string // uuid
  name: string
  useCaseEnabled: boolean
  eventCatalogEvent?: string
  eventEnabled?: boolean
  webhooks?: Array<{
    webhookId: string
    webhookName?: string
    enabled?: boolean
  }>
  status: "ok" | "conflict" | "disabled"
  conflicts?: Array<{
    type: "event_disabled" | "all_webhooks_disabled" | "event_enabled_while_disabled" | "webhook_enabled_while_disabled" | "stream_blocked" | "dlq_items_present"
    webhookId?: string
    message: string
  }>
  poll?: {
    queue_depth: number
    oldest_unconsumed_age_seconds: number
    last_poll_at: string // date-time
    last_ack_at: string // date-time
    blocked: boolean
    dlq_count: number
  }
  file_proxy?: Array<{
    mapping_id: string
    use_case_slug: string
    resolved: boolean
    target_use_case_id?: string // uuid
    target_enabled?: boolean
    target_updated_at?: string // date-time
    unresolved_reason?: "not_found" | "wrong_type" | "wrong_direction" | "disabled"
  }>
}

OutboundFileProxyTargetStatus​

Resolution state of one file_proxy mapping's referenced upload use case.

Because the transport lives on a separate use case, edits to the endpoint or credentials do not appear in THIS use case's history. target_updated_at is the hook that lets an operator notice a target changed underneath a deli

type OutboundFileProxyTargetStatus = {
  mapping_id: string
  use_case_slug: string
  resolved: boolean
  target_use_case_id?: string // uuid
  target_enabled?: boolean
  target_updated_at?: string // date-time
  unresolved_reason?: "not_found" | "wrong_type" | "wrong_direction" | "disabled"
}

OutboundPollStatus​

Queue/consumer health for a poll-mode use case. Present only on use cases with a poll delivery mapping — webhook-only use cases are unaffected. Depth/age/DLQ numbers are first-page approximations.

type OutboundPollStatus = {
  queue_depth: number
  oldest_unconsumed_age_seconds: number
  last_poll_at: string // date-time
  last_ack_at: string // date-time
  blocked: boolean
  dlq_count: number
}

WebhookStatus​

type WebhookStatus = {
  webhookId: string
  webhookName?: string
  enabled?: boolean
}

OutboundConflict​

type OutboundConflict = {
  type: "event_disabled" | "all_webhooks_disabled" | "event_enabled_while_disabled" | "webhook_enabled_while_disabled" | "stream_blocked" | "dlq_items_present"
  webhookId?: string
  message: string
}

PollOutboundMessagesRequest​

type PollOutboundMessagesRequest = {
  limit?: number
}

OutboundMessage​

type OutboundMessage = {
  id: string
  lease_token: string
  use_case_id: string
  event_name: string
  event_id: string
  group: string
  org_id?: string
  payload: Record<string, unknown>
  mapping_version?: string
  enqueued_at: string // date-time
}

PollOutboundMessagesResponse​

type PollOutboundMessagesResponse = {
  messages: Array<{
    id: string
    lease_token: string
    use_case_id: string
    event_name: string
    event_id: string
    group: string
    org_id?: string
    payload: Record<string, unknown>
    mapping_version?: string
    enqueued_at: string // date-time
  }>
  visibility_timeout_seconds: number
  has_more: boolean
}

AckOutboundMessagesRequest​

type AckOutboundMessagesRequest = {
  acks: Array<{
    id: string
    lease_token: string
  }>
}

AckResult​

type AckResult = {
  id: string
  status: "accepted" | "rejected"
  reason?: "stale_lease" | "out_of_order" | "not_found"
}

AckOutboundMessagesResponse​

type AckOutboundMessagesResponse = {
  results: Array<{
    id: string
    status: "accepted" | "rejected"
    reason?: "stale_lease" | "out_of_order" | "not_found"
  }>
}

OutboundDlqMessage​

type OutboundDlqMessage = {
  id: string
  use_case_id: string
  event_name: string
  event_id: string
  enqueued_at?: string // date-time
  dead_lettered_at: string // date-time
  delivery_attempts: number
  reason?: string
  mapping_error?: string
  mapping_version?: string
  expires_at?: string // date-time
}

OutboundDlqListResponse​

type OutboundDlqListResponse = {
  items: Array<{
    id: string
    use_case_id: string
    event_name: string
    event_id: string
    enqueued_at?: string // date-time
    dead_lettered_at: string // date-time
    delivery_attempts: number
    reason?: string
    mapping_error?: string
    mapping_version?: string
    expires_at?: string // date-time
  }>
  next_token?: string
}

RedriveOutboundDlqRequest​

type RedriveOutboundDlqRequest = {
  ids: string[]
  reapply_mapping?: boolean
}

RedriveOutboundDlqResult​

type RedriveOutboundDlqResult = {
  id: string
  status: "redriven" | "not_found" | "mapping_failed"
  mapping_error?: string
}

RedriveOutboundDlqResponse​

type RedriveOutboundDlqResponse = {
  results: Array<{
    id: string
    status: "redriven" | "not_found" | "mapping_failed"
    mapping_error?: string
  }>
}

UnblockOutboundStreamRequest​

type UnblockOutboundStreamRequest = {
  reason?: string
}

UnblockOutboundStreamResponse​

type UnblockOutboundStreamResponse = {
  unblocked: boolean
  dead_lettered_id?: string
}

SimulateOutboundMappingRequest​

Exactly one of payload or event_id is required. event_id needs event_catalog_event to name the event it belongs to.

type SimulateOutboundMappingRequest = {
  jsonata_expression: string
  payload?: Record<string, unknown>
  event_id?: string
  event_catalog_event?: string
}

OutboundMappingSimulationError​

type OutboundMappingSimulationError = {
  code: "syntax_error" | "unknown_binding" | "evaluation_error" | "timeout" | "invalid_output" | "expression_too_long"
  message: string
  position?: number
}

SimulateOutboundMappingResponse​

type SimulateOutboundMappingResponse = {
  valid: boolean
  output?: Record<string, unknown>
  error?: {
    code: "syntax_error" | "unknown_binding" | "evaluation_error" | "timeout" | "invalid_output" | "expression_too_long"
    message: string
    position?: number
  }
  mapping_version: string
  input?: Record<string, unknown>
}

RelationConfig​

type RelationConfig = {
  operation: "_set" | "_append" | "_append_all"
  items?: Array<{
    entity_schema: string
    _tags?: string[]
    unique_ids: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
    required?: boolean
  }>
  jsonataExpression?: string
}

RelationItemConfig​

type RelationItemConfig = {
  entity_schema: string
  _tags?: string[]
  unique_ids: Array<{
    attribute: string
    _type?: "email" | "phone"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }>
  required?: boolean
}

RelationUniqueIdField​

type RelationUniqueIdField = {
  attribute: string
  _type?: "email" | "phone"
  field?: string
  jsonataExpression?: string
  constant?: unknown
}

RelationRefsConfig​

Configuration for relation references ($relation_ref). Relation references link to a specific item within a repeatable attribute on a related entity. Common use case: referencing a specific address within a contact's address list.

type RelationRefsConfig = {
  operation: "_set" | "_append" | "_append_all"
  items?: Array<{
    entity_schema: string
    unique_ids: Array<{
      attribute: { ... }
      _type?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }>
    path: string
    value: {
      attribute: { ... }
      operation?: { ... }
      field?: { ... }
      jsonataExpression?: { ... }
      constant?: { ... }
    }
  }>
  jsonataExpression?: string
}

RelationRefItemConfig​

Configuration for a single relation reference item

type RelationRefItemConfig = {
  entity_schema: string
  unique_ids: Array<{
    attribute: string
    _type?: "email" | "phone"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }>
  path: string
  value: {
    attribute: string
    operation?: "_set" | "_append" | "_append_all"
    field?: string
    jsonataExpression?: string
    constant?: unknown
  }
}

RelationRefValueConfig​

Configuration for the value to set on the related entity's attribute

type RelationRefValueConfig = {
  attribute: string
  operation?: "_set" | "_append" | "_append_all"
  field?: string
  jsonataExpression?: string
  constant?: unknown
}

RepeatableFieldType​

Type hint for repeatable fields that require special search handling. These fields are stored as arrays of objects (e.g., email: [{ email: "value" }]).

type RepeatableFieldType = "email" | "phone"

ReplayEventsRequest​

type ReplayEventsRequest = {
  event_ids: string[]
}

QueryEventsRequest​

type QueryEventsRequest = {
  event_id?: string
  event_type?: "CREATE" | "UPDATE" | "DELETE"
  correlation_id?: string
  object_type?: string
  event_name?: string
  use_case_id?: string
  limit?: number
  cursor?: {
    event_time?: string // date-time
    event_id?: string
  }
}

QueryInboundMonitoringEventsRequest​

type QueryInboundMonitoringEventsRequest = {
  use_case_id?: string // uuid
  event_type?: "CREATE" | "UPDATE" | "DELETE" | "TRIGGER"
  sync_type?: "entity" | "meter_reading" | "webhook" | "api_deprecation"
  status?: "success" | "error" | "skipped" | "warning"
  error_category?: "validation" | "configuration" | "downstream_api" | "timeout" | "system"
  correlation_id?: string
  object_type?: string
  event_name?: string
  event_id?: string
  from_date?: string // date-time
  to_date?: string // date-time
  limit?: number
  cursor?: {
    completed_at?: string // date-time
    event_id?: string
  }
}

QueryAccessLogsRequest​

type QueryAccessLogsRequest = {
  token_id?: string
  service?: string
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD"
  path?: string
  status?: number
  from_date?: string // date-time
  to_date?: string // date-time
  limit?: number
  cursor?: {
    timestamp?: string // date-time
    request_id?: string
  }
}

AccessLogEntry​

type AccessLogEntry = {
  timestamp?: string // date-time
  environment?: string
  service?: string
  request_id?: string
  method?: string
  path?: string
  status?: number
  response_latency_ms?: number
  response_length?: number
  token_id?: string
  org_id?: string
  origin?: string
  source_ip?: string
}

GetMonitoringStatsRequest​

type GetMonitoringStatsRequest = {
  from_date?: string // date-time
  to_date?: string // date-time
  inbound_group_by?: "use_case_id" | "sync_type" | "status" | "error_category" | "object_type" | "event_name" | "date"[]
  outbound_group_by?: "event_name" | "status" | "webhook_config_id" | "date"[]
}

GetMonitoringTimeSeriesRequest​

type GetMonitoringTimeSeriesRequest = {
  from_date: string // date-time
  to_date?: string // date-time
  interval: "5m" | "10m" | "30m" | "1h" | "3h" | "1d"
  direction?: "inbound" | "outbound" | "both"
}

TimeSeriesBucket​

type TimeSeriesBucket = {
  timestamp: string // date-time
  inbound?: {
    success_count?: number
    error_count?: number
    warning_count?: number
    skipped_count?: number
    total_count?: number
  }
  outbound?: {
    success_count?: number
    error_count?: number
    pending_count?: number
    total_count?: number
  }
}

QueryOutboundMonitoringEventsRequest​

type QueryOutboundMonitoringEventsRequest = {
  event_name?: string
  status?: "succeeded" | "failed" | "pending"
  webhook_config_id?: string
  from_date?: string // date-time
  to_date?: string // date-time
  limit?: number
  cursor?: {
    created_at?: string // date-time
    event_id?: string
  }
}

OutboundMonitoringEvent​

type OutboundMonitoringEvent = {
  org_id: string
  event_id: string
  event_name: string
  status: "succeeded" | "failed" | "pending"
  url?: string
  http_method?: string
  http_response?: Record<string, unknown>
  webhook_config_id?: string
  metadata?: Record<string, unknown>
  execution_context?: Record<string, unknown>
  payload?: Record<string, unknown>
  created_at: string // date-time
  updated_at?: string // date-time
}

MonitoringStats​

type MonitoringStats = {
  inbound: {
    total_events: number
    total_correlations?: number
    success_count: number
    error_count: number
    skipped_count: number
    warning_count?: number
    success_rate?: number
    last_error_at?: string // date-time
    breakdown?: Record<string, unknown>[]
  }
  outbound: {
    total_events: number
    success_count: number
    error_count: number
    pending_count?: number
    success_rate?: number
    last_error_at?: string // date-time
    breakdown?: Record<string, unknown>[]
  }
}

InboundMonitoringEvent​

type InboundMonitoringEvent = {
  org_id: string
  event_id: string
  correlation_id?: string
  integration_id?: string
  use_case_id?: string
  event_type?: "CREATE" | "UPDATE" | "DELETE" | "TRIGGER"
  object_type: string
  sync_type: "entity" | "meter_reading" | "webhook" | "api_deprecation"
  status: "success" | "error" | "skipped" | "warning"
  error_code?: string
  error_message?: string
  error_category?: "validation" | "configuration" | "downstream_api" | "timeout" | "system"
  processing_duration_ms?: number
  received_at: string // date-time
  completed_at: string // date-time
}

QueryMonitoringEventsV2Request​

type QueryMonitoringEventsV2Request = {
  use_case_id?: string
  use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
  level?: "success" | "error" | "info" | "warning" | "skipped"
  code?: string
  event_id?: string
  correlation_id?: string
  from_date?: string // date-time
  to_date?: string // date-time
  limit?: number
  cursor?: {
    created_at?: string // date-time
    id?: string // uuid
  }
}

ExternalMonitoringSpan​

A single monitoring span produced by an external system. correlation_id, level, use_case_slug, occurred_at and message are all required and level must be one of success|error|warning|info — but these are validated PER SPAN at ingest and reported in the per-item results[], so one malfor

type ExternalMonitoringSpan = {
  correlation_id?: string
  level?: string
  use_case_slug?: string
  occurred_at?: string // date-time
  message?: string
  detail?: Record<string, unknown>
}

IngestExternalMonitoringEventsRequest​

type IngestExternalMonitoringEventsRequest = {
  events: Array<{
    correlation_id?: string
    level?: string
    use_case_slug?: string
    occurred_at?: string // date-time
    message?: string
    detail?: Record<string, unknown>
  }>
}

IngestExternalMonitoringEventsResponse​

type IngestExternalMonitoringEventsResponse = {
  accepted: number
  rejected: number
  results?: Array<{
    index: number
    status: "accepted" | "rejected"
    reason?: string
  }>
}

MonitoringTraceResponse​

type MonitoringTraceResponse = {
  correlation_id: string
  status: "success" | "error" | "warning" | "info"
  started_at?: string // date-time
  ended_at?: string // date-time
  span_count: number
  truncated: boolean
  spans: Array<{
    id: string // uuid
    org_id: string
    integration_id: string
    event_id: string
    correlation_id?: string
    use_case_id?: string
    use_case_type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" | ""
    level: "success" | "error" | "info" | "warning"
    code?: "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED" | string
    message?: string
    detail?: Record<string, unknown>
    created_at: string // date-time
  }>
  inbound_event?: Record<string, unknown>
}

MonitoringCode​

The monitoring code taxonomy — every code the Integration Toolkit itself emits, with a fixed level (see the published code reference at https://docs.epilot.io/docs/integrations/integration-toolkit/monitoring/codes).

This schema exists so consumers can import the union as a type. It never constrains

type MonitoringCode = "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED"

MonitoringEventV2​

type MonitoringEventV2 = {
  id: string // uuid
  org_id: string
  integration_id: string
  event_id: string
  correlation_id?: string
  use_case_id?: string
  use_case_type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" | ""
  level: "success" | "error" | "info" | "warning"
  code?: "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED" | string
  message?: string
  detail?: Record<string, unknown>
  created_at: string // date-time
}

GetMonitoringStatsV2Request​

type GetMonitoringStatsV2Request = {
  from_date?: string // date-time
  to_date?: string // date-time
  correlation_id?: string
  correlation_ids?: string[]
  use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
  use_case_types?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"[]
  group_by?: "use_case_id" | "use_case_type" | "level" | "code" | "correlation_id" | "date"
  source?: "monitoring" | "incoming"
}

GetMonitoringRunCompletionV2Request​

type GetMonitoringRunCompletionV2Request = {
  correlation_ids: string[]
}

MonitoringRunCompletionV2Response​

type MonitoringRunCompletionV2Response = {
  runs: Array<{
    correlation_id: string
    seen: number
    in_flight: number
    retrying: number
    success: number
    warning: number
    error: number
    info: number
    entries: {
      total: { ... }
      error: { ... }
      warning: { ... }
      success: { ... }
      info: { ... }
      retry: { ... }
    }
    last_activity_at: string // date-time
  }>
}

MonitoringRunCompletionV2​

Per-event completion of one run. Every count is in EVENTS (distinct event_id), never rows: seen = in_flight + success + warning + error + info.

type MonitoringRunCompletionV2 = {
  correlation_id: string
  seen: number
  in_flight: number
  retrying: number
  success: number
  warning: number
  error: number
  info: number
  entries: {
    total: number
    error: number
    warning: number
    success: number
    info: number
    retry: number
  }
  last_activity_at: string // date-time
}

MonitoringRunEntriesV2​

The run's monitoring rows counted by level — the rows its trace lists, correlation-level rows (wait outcomes, closes) included. Unlike the event counts above, one event can contribute many rows (one per entity written, plus every caveat and retry). Retry markers count under retry only, so a failed

type MonitoringRunEntriesV2 = {
  total: number
  error: number
  warning: number
  success: number
  info: number
  retry: number
}

MonitoringStatsV2​

type MonitoringStatsV2 = {
  total_events: number
  success_count: number
  error_count: number
  warning_count: number
  skipped_count: number
  info_count: number
  ack_timeout_count?: number
  success_rate?: number
  last_error_at?: string // date-time
  last_event_at?: string // date-time
  breakdown?: Record<string, unknown>[]
}

GetMonitoringTimeSeriesV2Request​

type GetMonitoringTimeSeriesV2Request = {
  from_date: string // date-time
  to_date?: string // date-time
  interval: "5m" | "10m" | "30m" | "1h" | "3h" | "1d"
  use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
  group_by?: "use_case_type" | "use_case"
}

TimeSeriesBreakdownItemV2​

type TimeSeriesBreakdownItemV2 = {
  use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
  use_case_id?: string
  success_count: number
  error_count: number
  warning_count: number
  skipped_count: number
  info_count: number
  total_count: number
}

TimeSeriesBucketV2​

type TimeSeriesBucketV2 = {
  timestamp: string // date-time
  success_count?: number
  error_count?: number
  warning_count?: number
  skipped_count?: number
  info_count?: number
  total_count: number
  breakdown?: Array<{
    use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"
    use_case_id?: string
    success_count: number
    error_count: number
    warning_count: number
    skipped_count: number
    info_count: number
    total_count: number
  }>
}

DocumentationPageSummary​

Documentation page metadata without the markdown content

type DocumentationPageSummary = {
  id: string
  integration_id: string // uuid
  scope: "integration" | "use_case"
  use_case_id?: string // uuid
  title: string
  created_at: string // date-time
  created_by?: string
  updated_at: string // date-time
  updated_by?: string
}

DocumentationPage​

A markdown documentation page of an integration

type DocumentationPage = {
  id: string
  integration_id: string // uuid
  scope: "integration" | "use_case"
  use_case_id?: string // uuid
  title: string
  created_at: string // date-time
  created_by?: string
  updated_at: string // date-time
  updated_by?: string
  content: string
}

UpsertDocumentationPageRequest​

type UpsertDocumentationPageRequest = {
  title: string
  content: string
}