New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Network triggers

A network trigger watches a connected source — a mailbox or a Microsoft Teams channel — and starts a network from a chosen template whenever a matching message arrives, with no person in the loop.

Every trigger belongs to the user who created it and runs with that user's identity, so a triggered run reaches exactly what its owner could reach by hand. All endpoints are scoped to the caller: you only ever see or change your own triggers. Before creating a trigger, connect its source under Integrations; List available sources reports which sources you have connected.

A trigger fires only on messages that arrive after it is enabled: the first poll records a starting position and matches nothing, so switching one on never replays a full inbox.

Endpoints 9

Paths are relative to /api

The trigger object

One rule linking a source to a network template.

Attributes

  • id integer

    The trigger's unique identifier.

  • name string

    A human-readable name.

  • source string

    The kind of source watched.

  • provider string

    The connected provider backing the source.

  • templateId string

    The network template a match runs.

  • enabled boolean

    Whether the trigger is active.

  • config object

    The source-specific filter and settings.

  • lastPolledAt nullable string

    When the trigger was last polled.

  • lastTriggeredAt nullable string

    When the trigger last started a run.

  • lastError nullable string

    The most recent error, or null.

  • createdAt nullable string

    When the trigger was created.

  • updatedAt nullable string

    When the trigger was last changed.

The trigger object 
{
  "id": 7,
  "name": "Support mailbox",
  "source": "email",
  "provider": "ms365mail",
  "templateId": "document_review",
  "enabled": true,
  "config": {
    "fromAddress": "customer@example.com",
    "subjectContains": "invoice"
  },
  "lastPolledAt": "2026-09-01T09:34:12Z",
  "lastTriggeredAt": "2026-09-01T09:30:00Z",
  "lastError": null,
  "createdAt": "2026-08-20T11:00:00Z",
  "updatedAt": "2026-09-01T09:34:12Z"
}

List available sources

GET /api/network-triggers/sources

Returns the sources the caller can build a trigger on and whether each is connected.

Returns each source a trigger can watch, the providers that back it, and whether the caller has connected them. Use connected to decide whether to offer a source or send the user to connect it under Integrations first.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns the available sources and their connection state.

Errors

  • 503 The integration credential store is unavailable on this deployment.
Request 
curl "$VDF_BASE_URL/api/network-triggers/sources" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "sources": [
    {
      "source": "email",
      "providers": [
        {
          "provider": "ms365mail",
          "connected": true,
          "account": "ada@example.com"
        },
        {
          "provider": "email",
          "connected": false,
          "account": null
        }
      ],
      "connected": true
    },
    {
      "source": "teams",
      "providers": [
        {
          "provider": "ms365teams",
          "connected": false,
          "account": null
        }
      ],
      "connected": false
    }
  ]
}

List triggers

GET /api/network-triggers

Returns the caller's triggers, newest first.

Returns the triggers owned by the caller. Filter to one source with the source query parameter.

Authentication
Bearer token How it works

Query parameters

  • source string

    Return only triggers for this source.

    Possible values
    • email
    • teams

Returns

Returns a list of trigger objects.

Request 
curl "$VDF_BASE_URL/api/network-triggers?source=email" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "triggers": [
    {
      "id": 7,
      "name": "Support mailbox",
      "source": "email",
      "provider": "ms365mail",
      "templateId": "document_review",
      "enabled": true,
      "config": {
        "fromAddress": "customer@example.com",
        "subjectContains": "invoice"
      },
      "lastPolledAt": "2026-09-01T09:34:12Z",
      "lastTriggeredAt": "2026-09-01T09:30:00Z",
      "lastError": null,
      "createdAt": "2026-08-20T11:00:00Z",
      "updatedAt": "2026-09-01T09:34:12Z"
    }
  ]
}

Create a trigger

POST /api/network-triggers

Creates a trigger that runs a template when a matching message arrives.

Creates a trigger for the caller. The source's provider must already be connected under Integrations, or the request is refused with 409. When provider is omitted, a connected provider for the source is chosen automatically. A new trigger starts enabled unless enabled is set to false; its first poll only records a starting position.

For a teams trigger, config must identify a channel with teamId and channelId, or a chat with chatId. For an email trigger, config may narrow matches with fromAddress, subjectContains, bodyContains, unreadOnly, and folder.

Authentication
Bearer token How it works

Body parameters application/json

  • source string Required

    The source to watch.

    Possible values
    • email
    • teams
  • name string Required

    A name for the trigger, 200 characters or fewer.

  • templateId string Required

    The network template a match runs. template_id is accepted as an alias.

  • provider string

    The connected provider backing the source. Defaults to a connected provider for the source. Use ms365mail or email for email, ms365teams for Teams.

  • config object

    Source-specific filter and settings.

  • enabled boolean

    Whether the trigger is active on creation.

    Defaults to true.

Returns

Returns the created trigger object in trigger.

Errors

  • 400 The definition is invalid: an unknown source or provider, a missing name or template, or a Teams trigger without a channel or chat.
  • 409 The source's provider is not connected for the caller.
  • 503 The integration credential store is unavailable on this deployment.
Request 
curl -X POST "$VDF_BASE_URL/api/network-triggers" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "email",
    "name": "Support mailbox",
    "templateId": "document_review",
    "provider": "ms365mail",
    "config": {
      "fromAddress": "customer@example.com",
      "subjectContains": "invoice"
    },
    "enabled": true
  }'
Response 201 
{
  "success": true,
  "trigger": {
    "id": 7,
    "name": "Support mailbox",
    "source": "email",
    "provider": "ms365mail",
    "templateId": "document_review",
    "enabled": true,
    "config": {
      "fromAddress": "customer@example.com",
      "subjectContains": "invoice"
    },
    "lastPolledAt": null,
    "lastTriggeredAt": null,
    "lastError": null,
    "createdAt": "2026-09-01T09:30:00Z",
    "updatedAt": "2026-09-01T09:30:00Z"
  }
}

Retrieve a trigger

GET /api/network-triggers/{trigger_id}

Returns one of the caller's triggers.

Returns a single trigger the caller owns.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger to retrieve.

Returns

Returns the trigger object in trigger.

Errors

  • 404 No such trigger belongs to the caller.
Request 
curl "$VDF_BASE_URL/api/network-triggers/7" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "trigger": {
    "id": 7,
    "name": "Support mailbox",
    "source": "email",
    "provider": "ms365mail",
    "templateId": "document_review",
    "enabled": true,
    "config": {
      "fromAddress": "customer@example.com",
      "subjectContains": "invoice"
    },
    "lastPolledAt": "2026-09-01T09:34:12Z",
    "lastTriggeredAt": "2026-09-01T09:30:00Z",
    "lastError": null,
    "createdAt": "2026-08-20T11:00:00Z",
    "updatedAt": "2026-09-01T09:34:12Z"
  }
}

Update a trigger

PATCH /api/network-triggers/{trigger_id}

Also available as PUT /api/network-triggers/{trigger_id}

Updates a trigger the caller owns. Supply only the fields you want to change; omitted fields keep their current values. A trigger's source cannot be changed. Re-enabling a trigger clears its last recorded error. PUT and PATCH behave identically.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger to update.

Body parameters application/json

  • name string

    A new name, 200 characters or fewer.

  • templateId string

    A new network template. template_id is accepted as an alias.

  • provider string

    A new provider for the source.

  • config object

    Replacement filter and settings.

  • enabled boolean

    Whether the trigger is active.

Returns

Returns the updated trigger object in trigger.

Errors

  • 400 The resulting definition is invalid.
  • 404 No such trigger belongs to the caller.
Request 
curl -X PATCH "$VDF_BASE_URL/api/network-triggers/7" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
Response 200 
{
  "success": true,
  "trigger": {
    "id": 7,
    "name": "Support mailbox",
    "source": "email",
    "provider": "ms365mail",
    "templateId": "document_review",
    "enabled": false,
    "config": {
      "fromAddress": "customer@example.com",
      "subjectContains": "invoice"
    },
    "lastPolledAt": "2026-09-01T09:34:12Z",
    "lastTriggeredAt": "2026-09-01T09:30:00Z",
    "lastError": null,
    "createdAt": "2026-08-20T11:00:00Z",
    "updatedAt": "2026-09-01T10:00:00Z"
  }
}

Delete a trigger

DEL /api/network-triggers/{trigger_id}

Permanently deletes a trigger the caller owns and its delivery history. This cannot be undone.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger to delete.

Returns

Returns success: true once the trigger is deleted.

Errors

  • 404 No such trigger belongs to the caller.
Request 
curl -X DELETE "$VDF_BASE_URL/api/network-triggers/7" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true
}

Preview a trigger

GET /api/network-triggers/{trigger_id}/preview

Also available as POST /api/network-triggers/{trigger_id}/preview

Returns the messages a trigger would fire on now, without firing.

Polls the trigger's source and returns the messages that match its filter, without starting any run or advancing the trigger's position. Use it to confirm a filter before enabling a trigger. Preview always looks back over a recent window, even for a trigger that has never polled. GET and POST behave identically.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger to preview.

Returns

Returns the matches the trigger would fire on.

Errors

  • 404 No such trigger belongs to the caller.
  • 409 The trigger cannot poll: its source is not connected or its settings are incomplete.
  • 502 The source could not be read.
Request 
curl "$VDF_BASE_URL/api/network-triggers/7/preview" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "matches": [
    {
      "externalId": "ms365mail:AAMkAGI2...",
      "summary": "customer@example.com: Invoice 1042 query",
      "occurredAt": "2026-09-01T09:29:00Z",
      "preview": "From: Grace Hopper <customer@example.com>\nSubject: Invoice 1042 query\n..."
    }
  ]
}

Run a trigger now

POST /api/network-triggers/{trigger_id}/run

Polls a trigger once and dispatches any matching messages immediately.

Runs one poll-and-dispatch pass for a trigger the caller owns, the same pass the background poller performs on a schedule. Any matching message starts a network run as the trigger's owner, and each message is delivered at most once. Returns a report of what the pass did.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger to run.

Returns

Returns a report of the pass in report.

Errors

  • 404 No such trigger belongs to the caller.
  • 502 A matching message could not be dispatched to run its network.
Request 
curl -X POST "$VDF_BASE_URL/api/network-triggers/7/run" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "report": {
    "triggerId": 7,
    "name": "Support mailbox",
    "polled": true,
    "primed": false,
    "matched": 1,
    "dispatched": 1,
    "skipped": 0,
    "failed": 0,
    "runIds": [
      "trigger-7"
    ],
    "error": ""
  }
}

List trigger deliveries

GET /api/network-triggers/{trigger_id}/events

Returns the recent deliveries recorded for a trigger.

Returns the trigger's recent deliveries, newest first — each message it acted on and what happened. The caller must own the trigger.

Authentication
Bearer token How it works

Path parameters

  • trigger_id integer Required

    The trigger whose deliveries to list.

Query parameters

  • limit integer

    Maximum deliveries to return, from 1 to 200.

    Defaults to 25.

Returns

Returns the recent deliveries.

Errors

  • 404 No such trigger belongs to the caller.
Request 
curl "$VDF_BASE_URL/api/network-triggers/7/events?limit=25" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "events": [
    {
      "id": 91,
      "externalId": "ms365mail:AAMkAGI2...",
      "status": "dispatched",
      "runId": "trigger-7",
      "summary": "customer@example.com: Invoice 1042 query",
      "error": null,
      "createdAt": "2026-09-01T09:30:00Z"
    }
  ]
}