Skip to content
Try free
Guides › Advanced: open the docs menu

API-driven workflows

Mammoth's REST API lets external systems trigger automations and monitor their status programmatically. This guide covers the trigger options, how to fetch results, and integration patterns such as fan-out, fan-in, and retry. A file-arrival trigger already exists for Data Consolidation automations (see Pattern 3 in Incremental processing). To push data into Mammoth from an external system, see Webhook data push.

Trigger patterns

API trigger (production)

Trigger an automation from any external system using Mammoth's REST API. Use this when you need to kick off a pipeline run from CI/CD, a scheduler, or another backend service.

PATCH /api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}
Authorization: Bearer {api_token}
Content-Type: application/json

{"patch": [{"op": "command", "path": "run"}]}

Supported scenarios:

  • CI/CD pipeline completes a deployment → trigger a data refresh for release metrics
  • Scheduled job in an external system → trigger a Mammoth automation at a precise time
  • Business system completes processing → kick off downstream data pipeline

Schedule trigger (production)

Configure automations to run on a time-based schedule (daily, weekly, monthly) without any external system integration. See Automations for the full setup guide.

File-arrival trigger (production)

A Data Consolidation automation watches a source Data Library folder and picks up files as they are added—no API call, polling, or scheduled run time needed. This is already available; see Incremental processing → Pattern 3 for the full setup.

Webhook data push

To send data into Mammoth from systems such as Shopify, Stripe, or Salesforce, create a webhook dataset. The external system POSTs its payload to the dataset's webhook URL and Mammoth ingests it. See Triggers for setup. To start a pipeline run from an external event, call the API trigger above.

Push patterns: Sending results to external systems

Export via API after pipeline completion

After a pipeline runs (triggered by API or schedule), fetch its results via the dataview's data endpoint:

GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}/data
Authorization: Bearer {api_token}

This returns an async Job. Poll it until its status resolves (success, failure, processing, or error), then read the result rows. For an actual downloadable CSV/Excel file rather than JSON rows, add an export step to the pipeline itself—that's configured in the pipeline, not requested ad hoc through this endpoint.

Use cases:

  • Pull clean data into a downstream system after Mammoth processing
  • Feed Mammoth output into a BI tool or warehouse via a scheduled script
  • Integrate Mammoth into a broader data orchestration workflow (Airflow, Prefect, etc.)

Notifying another system on completion

Messaging delivers by email. To notify another system when a run finishes, poll the automation or Job status as shown in this guide, then POST to your own endpoint from your system.

Direct API write via external system

For writing results back to an API, the pattern requires an intermediary:

  1. Mammoth prepares the transformed data
  2. Export → Databases to BigQuery, PostgreSQL, SQL Server, or Redshift (kept current by Auto-sync on each pipeline run)
  3. A lightweight external script (Cloud Function, Lambda, Make.com webhook) reads from that database and writes to the target API

Mammoth does not write to arbitrary APIs. Use it for transformation and delegate API writes to a purpose-built integration tool.

Mammoth's external API

Mammoth's REST API allows external systems to trigger and monitor automations programmatically. The active API is versioned at /api/v2.

Key endpoints

Trigger an automation:

PATCH /api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}
Authorization: Bearer {api_token}
Content-Type: application/json

{"patch": [{"op": "command", "path": "run"}]}

Get an automation's last run status:

GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}
Authorization: Bearer {api_token}
# Returns last_run and last_run_result: Mammoth surfaces the most recent run, not a full run history

Fetch a View's data:

GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}/data
Authorization: Bearer {api_token}
# Async job: poll until status is "success", then read the result

Check View status:

GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}
Authorization: Bearer {api_token}
# Returns row_count, status, pipeline_status: there's no last-refreshed timestamp field

API authentication

API credentials are API tokens, created in Workspace settings → API Tokens. A token starts with mm_ and belongs to one workspace, not to an individual user; it can also be limited to one project, and then gets HTTP 403 in every other project. Requests send it as Authorization: Bearer {api_token}; no workspace header is needed, and the workspace id in the URL path must be the token's own workspace. The older X-API-KEY and X-API-SECRET headers are deprecated. See Authentication.

Security:

  • A token is shown only once—store it securely in your secrets manager
  • Rotate credentials when team members change or access needs change

Polling pattern for long-running pipelines

For pipelines that take minutes to complete, use polling rather than synchronous waiting:

import requests
import time

headers = {
    "Authorization": f"Bearer {api_token}",
}

# Trigger the automation
requests.patch(
    f"https://app.mammoth.io/api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}",
    headers=headers,
    json={"patch": [{"op": "command", "path": "run"}]},
)

# Poll the View for the refreshed status
while True:
    view = requests.get(
        f"https://app.mammoth.io/api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}",
        headers=headers,
    ).json()

    if view["pipeline_status"] == "ready":
        break
    elif view["pipeline_status"] == "error":
        raise Exception(f"Pipeline failed for dataview {dataview_id}")

    time.sleep(30)  # Check every 30 seconds

print("Pipeline completed. Fetching results...")

Integration patterns

The fan-out pattern

One file drop can already trigger multiple independent automations today. Create a separate Data Consolidation automation on the same source folder for each downstream pipeline that needs to react. Each one runs automatically whenever a file is added to the folder; Data Consolidation has no schedule or trigger setting to configure. For fan-out from other external events, call each automation's API trigger endpoint in turn from your external system.

The fan-in pattern

Multiple Mammoth automations must all complete before a downstream pipeline runs. Use a coordination layer outside Mammoth:

  1. Each upstream Mammoth automation is triggered via API
  2. Your coordination script polls each automation's status until complete
  3. When all prerequisites finish, it triggers the downstream automation via the API

The retry pattern

For flaky source systems (APIs that occasionally return errors or empty responses):

  1. Trigger the automation via API
  2. Poll for completion—if status is error, inspect the failure
  3. Retry by triggering it again up to N times with a delay between attempts
  4. If all retries fail, alert via your external notification system

Report an issue · support@mammoth.io