Skip to main content

Queries

Root query operations for cloud event indexes and full cloud events.

Overview​

The Fetch API exposes five root queries:

  • latestIndex – The most recent cloud event index matching optional filters.
  • indexes – A list of cloud event indexes (header + indexKey) matching optional filters.
  • latestCloudEvent – The most recent full cloud event (header + optional data).
  • cloudEvents – A list of full cloud events matching optional filters.
  • availableCloudEventTypes – A summary of which cloud event types exist for a subject, with counts and time ranges. Useful for discovery before running a full query.

All queries require a did (Decentralized Identifier). The did parameter accepts any DID in the DIMO system (e.g. did:erc721:1:0xContractAddress:tokenId). List queries accept an optional limit (default 10) and filter (CloudEventFilter).

Large or binary payloads

Some event types are too big to inline as JSON. Uploaded documents (dimo.document.*) and raw blobs are the common ones. When you select data or dataBase64 on these events, the Fetch API gives you a presigned S3 URL on dataUrl instead. Always request dataUrl alongside data if there is any chance you are querying a document or raw-blob type, otherwise you will get back a response with no payload.

latestIndex​

Returns the latest cloud event index (header + indexKey) that matches the given filter. Use this when you only need the index entry, not the full payload.

Arguments

didString!Required
DID identifier (e.g. did:erc721:1:0x...:tokenId).
filterCloudEventFilterOptional
Optional filter by id, type, types (OR list), dataversion, source, producer, before, after.
query GetLatestIndex {
latestIndex(
  did: "did:erc721:1:0x...:tokenId",
  filter: { type: "dimo.status" }
) {
  header { id type time source producer }
  indexKey
}
}

indexes​

Returns a list of cloud event indexes matching the filter. Each item includes header and indexKey.

Arguments

didString!Required
DID identifier (e.g. did:erc721:1:0x...:tokenId).
limitIntOptional
Maximum number of results (default: 10).
filterCloudEventFilterOptional
Optional filter by id, type, types (OR list), dataversion, source, producer, before, after.
query ListIndexes {
indexes(
  did: "did:erc721:1:0x...:tokenId",
  limit: 10,
  filter: { type: "dimo.status", after: "2024-06-01T00:00:00Z" }
) {
  header { id type time }
  indexKey
}
}

latestCloudEvent​

Returns the most recent full cloud event (header and optionally data / dataBase64) that matches the filter.

Arguments

didString!Required
DID identifier (e.g. did:erc721:1:0x...:tokenId).
filterCloudEventFilterOptional
Optional filter by id, type, types (OR list), dataversion, source, producer, before, after.
query GetLatestCloudEvent {
latestCloudEvent(
  did: "did:erc721:1:0x...:tokenId",
  filter: { type: "dimo.status" }
) {
  header { id type time source producer }
  data
  dataUrl
}
}

cloudEvents​

Returns a list of full cloud events matching the filter. Request only the fields you need (header, data, dataBase64).

Arguments

didString!Required
DID identifier (e.g. did:erc721:1:0x...:tokenId).
limitIntOptional
Maximum number of results (default: 10).
filterCloudEventFilterOptional
Optional filter by id, type, types (OR list), dataversion, source, producer, before, after.
query ListCloudEvents {
cloudEvents(
  did: "did:erc721:1:0x...:tokenId",
  limit: 5,
  filter: { types: ["dimo.document.vehicle.insurance", "dimo.document.vehicle.registration"] }
) {
  header { id type time raweventid }
  data
  dataUrl
}
}

availableCloudEventTypes​

Returns a list of CloudEventTypeSummary entries describing every cloud event type stored for the subject, along with counts and first/last-seen timestamps. Useful as a discovery query. For example, run it against a vehicle DID to see which dimo.document.* types have been uploaded before you commit to a full cloudEvents call.

Arguments

didString!Required
DID identifier (e.g. did:erc721:1:0x...:tokenId).
filterCloudEventFilterOptional
Optional filter by id, type, types, dataversion, source, producer, before, after. Applied before aggregating counts.
query AvailableTypes {
availableCloudEventTypes(
  did: "did:erc721:1:0x...:tokenId"
) {
  type
  count
  firstSeen
  lastSeen
}
}

Example: cURL​

Send a POST request with your query and JWT:

curl -X POST "https://fetch-api.dimo.zone/query" \\
  -H "Authorization: Bearer <JWT>" \\
  -H "Content-Type: application/json" \\
  -d '{"query":"query { latestCloudEvent(did: \"did:erc721:1:0x...:tokenId\", filter: { type: \"dimo.status\" }) { header { id type time } data } }"}'