Triggers - Planasonix

These endpoints manage event-driven triggers (cloud object notifications, webhooks, file watchers) that start pipeline runs when external conditions are met. Authenticate with a Bearer API key. Base URL: https://api.planasonix.com

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

If your workspace uses a versioned base path (for example /v1), prepend it before /api. See API reference.

List triggers

Returns all triggers configured in the workspace. GET /api/triggers

Request parameters

string

Filter triggers for a single pipeline.

string

Filter by trigger type: s3, gcs, azure, webhook, file_watcher, or deployment-specific values.

integer

default:"50"

Page size.

string

Pagination cursor from a previous response.

Example response

{
  "data": [
    {
      "id": "trg_01j9k4w8x9y0z1a2",
      "type": "trigger",
      "attributes": {
        "name": "ingest-landing-s3",
        "trigger_type": "s3",
        "pipeline_id": "pl_01hq8raw_ingest",
        "enabled": true,
        "created_at": "2025-02-01T10:00:00Z",
        "updated_at": "2025-03-20T11:45:00Z"
      }
    }
  ],
  "meta": {
    "page": { "limit": 50, "cursor": null }
  }
}

Create trigger

Creates a trigger. The request body shape depends on triggerType (S3, GCS, Azure Blob, generic webhook, or file watcher). Below is a representative S3 configuration; other types use analogous connection and path or subscription fields. POST /api/triggers

Request body (common)

string

required

Human-readable name.

string

required

One of s3, gcs, azure, webhook, file_watcher.

string

required

Pipeline to run when the trigger fires.

boolean

default:"true"

Whether the trigger accepts events when created.

Request body (S3 example)

string

required

AWS connection ID with permission to read the bucket and manage notifications where applicable.

string

required

S3 bucket name.

string

Object key prefix filter (optional).

string

Object key suffix filter (for example .parquet).

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "name": "ingest-landing-s3",
      "trigger_type": "s3",
      "pipeline_id": "pl_01hq8raw_ingest",
      "enabled": true,
      "config": {
        "bucket": "acme-analytics-landing",
        "prefix": "uploads/daily/",
        "suffix": ".csv"
      },
      "created_at": "2025-03-27T16:00:00Z",
      "updated_at": "2025-03-27T16:00:00Z"
    }
  }
}

Get trigger

Returns one trigger including configuration metadata (secrets are never returned). GET /api/triggers/{id}

Request parameters

string

required

Trigger ID.

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "name": "ingest-landing-s3",
      "trigger_type": "s3",
      "pipeline_id": "pl_01hq8raw_ingest",
      "enabled": true,
      "config": {
        "bucket": "acme-analytics-landing",
        "prefix": "uploads/daily/",
        "suffix": ".csv"
      },
      "created_at": "2025-02-01T10:00:00Z",
      "updated_at": "2025-03-20T11:45:00Z"
    }
  }
}

Update trigger

Updates trigger metadata or configuration. Immutable fields (such as provider identifiers on some trigger types) may return 409 Conflict if changed. PUT /api/triggers/{id}

Request parameters

string

required

Trigger ID.

Request body

Fields are optional; send only what you want to change (name, enabled, type-specific config, and so on).

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "name": "ingest-landing-s3-v2",
      "trigger_type": "s3",
      "pipeline_id": "pl_01hq8raw_ingest",
      "enabled": true,
      "config": {
        "bucket": "acme-analytics-landing",
        "prefix": "uploads/hourly/",
        "suffix": ".parquet"
      },
      "updated_at": "2025-03-27T16:20:00Z"
    }
  }
}

Delete trigger

Removes the trigger and tears down provider-side subscriptions when the platform manages them. DELETE /api/triggers/{id}

Request parameters

string

required

Trigger ID.

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "deleted": true,
      "deleted_at": "2025-03-27T16:25:00Z"
    }
  }
}

Enable trigger

POST /api/triggers/{id}/enable

Request parameters

string

required

Trigger ID.

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "enabled": true,
      "updated_at": "2025-03-27T16:26:00Z"
    }
  }
}

Disable trigger

POST /api/triggers/{id}/disable

Request parameters

string

required

Trigger ID.

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger",
    "attributes": {
      "enabled": false,
      "updated_at": "2025-03-27T16:27:00Z"
    }
  }
}

Test trigger

Validates configuration and optionally performs a dry-run handshake with the provider. Does not enqueue a full pipeline run unless the API explicitly returns a run ID for the test. POST /api/triggers/{id}/test

Request parameters

string

required

Trigger ID.

Example response

{
  "data": {
    "id": "trg_01j9k4w8x9y0z1a2",
    "type": "trigger_test",
    "attributes": {
      "status": "ok",
      "checked_at": "2025-03-27T16:28:00Z",
      "message": "S3 bucket notification reachable; subscription active.",
      "latency_ms": 142
    }
  }
}

List trigger executions

Returns recent executions initiated by this trigger (pagination supported). GET /api/triggers/{id}/executions

Request parameters

string

required

Trigger ID.

string

Filter by run status: queued, running, succeeded, failed, canceled.

integer

default:"25"

Page size.

string

Pagination cursor.

Example response

{
  "data": [
    {
      "id": "tex_01j9k5b1c2d3e4f5",
      "type": "trigger_execution",
      "attributes": {
        "trigger_id": "trg_01j9k4w8x9y0z1a2",
        "pipeline_run_id": "run_01j9k5a0z9y8x7w6",
        "status": "succeeded",
        "event_summary": "s3:ObjectCreated:Put s3://acme-analytics-landing/uploads/daily/2025-03-27/part-0001.csv",
        "started_at": "2025-03-27T06:01:02Z",
        "finished_at": "2025-03-27T06:04:18Z"
      }
    }
  ],
  "meta": {
    "page": { "limit": 25, "cursor": "eyJpZCI6InRleF8wMWo5azViMWMyZDNlNGY1In0" }
  }
}

Webhook ingress (S3)

Provider-facing URL that receives Amazon S3 event notifications (for example SNS → HTTPS or Lambda-forwarded payloads, depending on your setup). Typically not called with your API key; the cloud provider signs or routes events per your subscription. POST /api/webhooks/s3

Request parameters

Headers and body follow AWS notification formats (SNS envelope or S3 event JSON). Planasonix validates the subscription and maps events to matching triggers.

Example response

{
  "received": true,
  "events_processed": 1
}

Webhook ingress (GCS)

Receives Google Cloud Storage object change notifications (Pub/Sub push or compatible JSON). POST /api/webhooks/gcs

Example response

{
  "received": true,
  "events_processed": 2
}

Webhook ingress (Azure)

Receives Azure Event Grid events for Blob Storage (and related) subscriptions. POST /api/webhooks/azure

Example response

{
  "received": true,
  "events_processed": 1
}

Webhook ingress (custom trigger)

Generic HTTPS endpoint for a webhook trigger type. The path includes the trigger identifier so events route to the correct pipeline configuration. POST /api/webhooks/trigger/{triggerId}

Request parameters

string

required

Trigger ID (trg_...).

Request body

Arbitrary JSON or raw body as configured on the trigger; optional HMAC or header-based verification may apply.

Example response

{
  "received": true,
  "pipeline_run_id": "run_01j9k5c6d7e8f9g0",
  "status": "accepted"
}

​List triggers

​Request parameters

​Example response

​Create trigger

​Request body (common)

​Request body (S3 example)

​Example response

​Get trigger

​Request parameters

​Example response

​Update trigger

​Request parameters

​Request body

​Example response

​Delete trigger

​Request parameters

​Example response

​Enable trigger

​Request parameters

​Example response

​Disable trigger

​Request parameters

​Example response

​Test trigger

​Request parameters

​Example response

​List trigger executions

​Request parameters

​Example response

​Webhook ingress (S3)

​Request parameters

​Example response

​Webhook ingress (GCS)

​Example response

​Webhook ingress (Azure)

​Example response

​Webhook ingress (custom trigger)

​Request parameters

​Request body

​Example response

List triggers

Request parameters

Example response

Create trigger

Request body (common)

Request body (S3 example)

Example response

Get trigger

Request parameters

Example response

Update trigger

Request parameters

Request body

Example response

Delete trigger

Request parameters

Example response

Enable trigger

Request parameters

Example response

Disable trigger

Request parameters

Example response

Test trigger

Request parameters

Example response

List trigger executions

Request parameters

Example response

Webhook ingress (S3)

Request parameters

Example response

Webhook ingress (GCS)

Example response

Webhook ingress (Azure)

Example response

Webhook ingress (custom trigger)

Request parameters

Request body

Example response