Skip to main content

Introduction

Retrieve raw data objects and index keys from cloud storage.

Overview​

The Fetch API provides access to raw data stored in the cloud, formatted as CloudEvents. It is written in GraphQL and exposes a single endpoint, /query, for executing queries. You can retrieve CloudEvent-formatted data and index keys by did (Decentralized Identifier), and request only the fields you need—for example, header and/or data. The did parameter accepts any DID in the DIMO system (e.g. a vehicle DID like did:eth:1:0xContractAddress:tokenId).

Base URL

https://fetch-api.dimo.zone

Endpoints

Developer Notes

To access data via the Fetch API, a token exchange is required to obtain a JWT with the appropriate permissions. The entity must have been shared with your app with raw data permission. When requesting the token (e.g. via the Token Exchange API), include the privilege that grants raw data access. See Authentication and the Token Exchange API for details.

Schema & Types​

CloudEvent

A full CloudEvent object. Select only the fields you need to keep responses small.

CloudEvent fields

headerCloudEventHeader!
CloudEvents v1.0 header metadata. Select individual sub-fields (see below).
dataJSON
The event payload as parsed JSON (object or array). Omitted from the response if not requested.
dataBase64String
The event payload as a base64-encoded string. Use this when the payload is binary or you need the raw bytes.

CloudEventHeader

CloudEvents v1.0 metadata fields. Required fields are always present; optional fields may be null.

Required header fields

idString!
Unique event identifier.
specversionString!
CloudEvents spec version (e.g. "1.0").
typeString!
Event type in reverse-DNS format (e.g. "dimo.status").
sourceString!
Source context that produced the event.
subjectString!
Subject of the event (typically the DID).
timeTime!
Timestamp of the event (RFC-3339, UTC).
producerString!
Instance, process, or device that produced the event.
tags[String!]!
Tags associated with the event.

Optional header fields

datacontenttypeString
Content type of the data payload (e.g. "application/json").
dataschemaString
URI of the schema the data payload conforms to.
dataversionString
Version of the data schema.
signatureString
Cryptographic signature of the event.

CloudEventIndex

A lightweight index entry referencing a stored CloudEvent. Contains the event header and a storage key for retrieval.

CloudEventIndex fields

headerCloudEventHeader!
CloudEvents header metadata (same fields as above).
indexKeyString!
Storage key that uniquely identifies this event in cloud storage.

CloudEventFilter

Optional filter for queries. All fields are optional—combine them to narrow results.

CloudEventFilter fields

id
Filter by event identifier.
type
Filter by event type (e.g. "dimo.status").
dataversion
Filter by data version string.
source
Filter by source context.
producer
Filter by producer (instance/process/device).
beforeTime
Return results before this time (RFC-3339).
afterTime
Return results after this time (RFC-3339).
# Full CloudEvent with all header fields

query {
latestCloudEvent(
  did: "did:eth:1:0x...:123456",
  filter: { type: "dimo.status" }
) {
  header {
    id
    specversion
    type
    source
    subject
    time
    producer
    tags
    datacontenttype
    dataschema
    dataversion
    signature
  }
  data
  dataBase64
}
}

Scalars​

The Fetch API uses two custom scalars in addition to GraphQL built-ins:

Time
A point in time, encoded per RFC-3339. Typically in UTC (e.g. 2024-06-01T12:00:00Z).
JSON
Arbitrary JSON value; serialized as raw JSON (object/array), not an escaped string. The structure depends on the event type.
# Minimal query — just header + data

query {
cloudEvents(
  did: "did:eth:1:0x...:123456",
  limit: 5,
  filter: { type: "dimo.status" }
) {
  header { id type time }
  data
}
}