Try it free

OpenPipeline Ingest API - POST Built-in Smartscape events

  • Latest Dynatrace
  • Reference
  • 1-min read
  • Published Jun 03, 2026

Ingests Smartscape events from built-in endpoints.

The request consumes an application/json payload.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/platform/ingest/v1/smartscape.events

Authentication

To execute this request, you need an access token with openpipeline.events_smartscape scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
bodySmartscapeEvents

The JSON body of the request. Contains the events for ingest.

bodyRequired

Request body objects

The SmartscapeEvents object

The Smartscape events to be ingested. This can either be a list of events, or a single event.

ElementTypeDescriptionRequired
<*>SmartscapeEvent[]

List of Smartscape events to be ingested.

Optional

The SmartscapeEvent object

A Smartscape node upsert event. Exactly one identity mode must be used: Mode 1 supplies a pre-computed id; Mode 2 supplies type + id_components and the server computes the ID. The two modes are mutually exclusive — supplying both id and type is rejected.

fields and tag contexts are top-level keys. Tag contexts use a tags: prefix (e.g. tags:ext.source).

ElementTypeDescriptionRequired
additionalPropertiesobject-Optional
dt.security_contextAnyValue

Security context. String or array of strings.

Optional
dynamic_edgesobject

Dynamic topology edges, keyed by relationship name. Each value is an array of target node references.

Optional
event.versioninteger

Schema version of this event. Optional — version 1 is applied when absent. Must be a known version; currently only 1 is accepted.

Optional
idstring

Pre-computed Smartscape entity ID (Mode 1). Must match [A-Z][A-Z0-9_]*-[0-9A-F]{16} (e.g. HOST-0000000000000001). Mutually exclusive with type.

Optional
id_componentsobject[]

Identity components used to compute the entity ID (Mode 2). Required when type is set; optional in Mode 1. Each entry must be a single-key object whose value is a string (e.g. [{"hostname": "myhost"}]).

Optional
static_edgesobject

Static topology edges, keyed by relationship name. Each value is an array of target node references.

Optional
timestampAnyValue

Event timestamp. Optional — current server time is used when absent. Accepted formats: RFC3339 string (e.g. 2024-01-01T00:00:00Z) or a positive number. Zero and negative numbers are rejected.

Optional
typestring

Entity type (Mode 2). Must match [A-Z][A-Z0-9_]* (e.g. HOST, HOST_GROUP). Mutually exclusive with id. Types starting with EXT_ or CUSTOM_ are treated as extended entity types and bypass the field-name allowlist.

Optional
update_lifetimeboolean

Whether to advance the entity's last-seen timestamp. Defaults to true. Set to false to update fields without refreshing the last-seen time.

Optional

The AnyValue object

A schema representing an arbitrary value type.

The SmartscapeEdge object

A reference to a related Smartscape node used to define a topology edge. Either id (Mode 1) or type + id_components (Mode 2) must be present. The two modes are mutually exclusive.

ElementTypeDescriptionRequired
idstring

Pre-computed ID of the related node (Mode 1). Must match [A-Z][A-Z0-9_]*-[0-9A-F]{16}. Mutually exclusive with type.

Optional
id_componentsobject[]

Identity components of the related node (Mode 2). Required when type is set; optional in Mode 1. Each entry must be a single-key object whose value is a string (e.g. [{"hostname": "myhost"}]).

Optional
typestring

Type of the related node (Mode 2). Must match [A-Z][A-Z0-9_]*. Mutually exclusive with id.

Optional

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

[
  {
    "event.version": 1,
    "type": "HOST",
    "id_components": [
      {
        "hostname": "myhost.example.com"
      }
    ],
    "dt.security_context": "my-security-context",
    "update_lifetime": true,
    "name": "my-host",
    "ext.custom.region": "eu-west-1",
    "primary_tags.env": "production",
    "tags:custom.infra": {
      "tier": "core"
    },
    "tags:ext.source": {
      "env": "production"
    },
    "static_edges": {
      "belongs_to": [
        {
          "type": "HOST_GROUP",
          "id_components": [
            {
              "group": "grp-1"
            }
          ]
        }
      ]
    },
    "dynamic_edges": {
      "runs_on": [
        {
          "id": "PROCESS_GROUP_INSTANCE-0000000000000001"
        }
      ]
    }
  }
]

Response

Response codes

CodeTypeDescription
202-

Accepted. Response doesn't have a body.

400ErrorResponseEnvelope

Failed. The input is invalid.

404ErrorResponseEnvelope

Failed. Endpoint not found.

413ErrorResponseEnvelope

Failed. Content too large.

429ErrorResponseEnvelope

Failed. Too many requests.

5XXErrorResponseEnvelope

Server-side error.

Response body objects

The ErrorResponseEnvelope object

Encloses the encountered error.

ElementTypeDescription
errorErrorResponse

Basic information of the encountered error.

The ErrorResponse object

Basic information of the encountered error.

ElementTypeDescription
codeinteger

The returned HTTP status code.

detailsErrorResponseDetails

Detailed information of the error.

messagestring

Description of the encountered error.

The ErrorResponseDetails object

Detailed information of the error.

ElementTypeDescription
typestring

Defines the actual set of fields depending on the value. See one of the following objects:

  • constraintViolation -> ConstraintViolationDetails
The element can hold these values
  • constraintViolation

Response body JSON models

{
  "error": {
    "code": 400,
    "message": "The input is invalid."
  }
}

Related topics

  • Smartscape on Grail
Related tags
Dynatrace Platform