External assets REST API reference#

As Dagster doesn't control scheduling or materializing external assets, it's up to you to keep their metadata updated. Use the endpoints described in this reference to report updates for external assets back to Dagster.

API functionality#

Using the External Asset APIs, you can:

• Report an AssetMaterialization event for an external asset to Dagster
• Report an asset_check evaluation for an external asset to Dagster
• Report an AssetObservation event for an external asset to Dagster

Authentication#

Authentication is required only if requests are being made against a Dagster+ instance. To authenticate, provide a valid Dagster+ user token using the Dagster-Cloud-Api-Token header:

curl --request POST \
    --url https://{ORGANIZATION}.dagster.cloud/{deployment_name}/report_asset_materialization/ \
    --header 'Content-Type: application/json' \
    --header 'Dagster-Cloud-Api-Token: {TOKEN}' \
    --data '{
        "asset_key": "{ASSET_KEY}",
        "metadata": {
            "rows": 10
        },
    }'

Constructing request URLs#

The full URL you send requests to will vary depending on how you access your Dagster instance:

Available APIs#

Report an asset materialization#

Records an AssetMaterialization event for an external asset. This event type notifies the Dagster framework that a materialized value has been produced for an asset.

Using this endpoint, you could report to Dagster that an external asset has been updated and include metadata about the materialization. For example, the number of updated rows, the time the update occurred, and so on.

Resources#

Parameters#

Parameters can be passed in multiple ways and will be considered in the following order:

1. URL (asset_key only)
2. Request body, which must be valid JSON
3. Query parameter

Returns#

The API will return JSON, whether the request succeeds or fails.

• 200 OK - Response body contains an empty object: {}
• 400 Bad request - Response body contains an error object: {"error": ...}

Examples#

curl -X POST localhost:3000/report_asset_materialization/{ASSET_KEY}

curl --request POST \
    --url https://{ORGANIZATION}.dagster.cloud/{DEPLOYMENT_NAME}/report_asset_materialization/ \
    --header 'Content-Type: application/json' \
    --header 'Dagster-Cloud-Api-Token: {TOKEN}' \
    --data '{
        "asset_key": "{ASSET_KEY}",
        "metadata": {
            "rows": 10
        },
    }'

import requests

url = "https://{ORGANIZATION}.dagster.cloud/{DEPLOYMENT_NAME}/report_asset_materialization/"

payload = {
    "asset_key": "ASSET_KEY",
    "metadata": {"rows": 10},
}
headers = {
    "Content-Type": "application/json",
    "Dagster-Cloud-Api-Token": "TOKEN"
}

response = requests.request("POST", url, json=payload, headers=headers)
response.raise_for_status()

import requests

url = f"{DAGSTER_WEBSERVER_HOST}/report_asset_materialization/{ASSET_KEY}"
response = requests.request("POST", url)
response.raise_for_status()

Report an asset check evaluation#

Records an AssetCheckEvaluation event for an external asset. This event type notifies the Dagster framework of the results of an executed check.

Using this endpoint, you could report to Dagster that an asset check has been executed and include metadata about the check. For example, if the check looks for null values in an id column, you could include the number of records with null IDs.

Resources#

Parameters#

Parameters can be passed in multiple ways and will be considered in the following order:

1. URL (asset_key only)
2. Request body, which must be valid JSON
3. Query parameter

Returns#

The API will return JSON, whether the request succeeds or fails.

• 200 OK - Response body contains an empty object: {}
• 400 Bad request - Response body contains an error object: {"error": ...}

Examples#

curl -X POST localhost:3000/report_asset_check/{ASSET_KEY}?check_name=check_null_ids&passed=true

curl --request POST \
    --url https://{ORGANIZATION}.dagster.cloud/{DEPLOYMENT_NAME}/report_asset_check/ \
    --header 'Content-Type: application/json' \
    --header 'Dagster-Cloud-Api-Token: {TOKEN}' \
    --data '{
        "asset_key": "{ASSET_KEY},
        "check_name": "check_null_ids",
        "passed": false,
        "metadata": {
            "null_rows": 3
        },
    }'

Report an asset observation#

Records an AssetObservation event for an external asset. This event type captures metadata about an asset at a point in time and provides it to the Dagster framework. Refer to the Asset observation documentation for more information.

Resources#

Parameters#

Parameters can be passed in multiple ways and will be considered in the following order:

1. URL (asset_key only)
2. Request body, which must be valid JSON
3. Query parameter

Returns#

The API will return JSON, whether the request succeeds or fails.

• 200 OK - Response body contains an empty object: {}
• 400 Bad request - Response body contains an error object: {"error": ...}

Examples#

curl -X POST localhost:3000/report_asset_observation/{ASSET_KEY}?data_version={VERSION}

curl --request POST \
    --url https://{ORGANIZATION}.dagster.cloud/{DEPLOYMENT_NAME}/report_asset_observation/ \
    --header 'Content-Type: application/json' \
    --header 'Dagster-Cloud-Api-Token: {TOKEN}' \
    --data '{
        "asset_key": "{ASSET_KEY}",
        "metadata": {
            "rows": 10
        },
        "data_version": "{VERSION}",
    }'