Sending discovery data with the API

If you have an agent, a script or another inventory tool, it can send device and software data to AssetTrove through the API. Create a discovery source of type Agent or script (API) first, and an API key with the Integration role.

The flow

Data arrives as a run, sent in one or more batches:

1. Open a run for the source, saying whether it's full (the complete list) or delta (only changes).
2. Send batches of up to 1,000 devices each.
3. Complete the run, saying how many batches you sent.

POST /api/v1/discovery/sources/{sourceId}/runs
Idempotency-Key: nightly-2026-11-12

{ "runType": "FULL", "expectedBatches": 12 }

POST /api/v1/discovery/runs/{runId}/batches
Idempotency-Key: {runId}:3
Content-Encoding: gzip

{
  "sequence": 3,
  "devices": [
    {
      "sourceDeviceKey": "agent:AMS-LT-0042",
      "observedAt": "2026-11-12T17:58:12Z",
      "hostname": "AMS-LT-0042",
      "serialNumber": "C02FK3XYMD6T",
      "manufacturer": "Apple Inc.",
      "model": "MacBook Pro (14-inch, 2023)",
      "os": { "name": "macOS", "version": "15.1" },
      "hardware": { "processors": 1, "coresPerProcessor": 12, "memoryMb": 32768 },
      "security": { "diskEncrypted": true },
      "lastLoggedOnUser": "jane.doe@example.com",
      "software": {
        "mode": "FULL",
        "items": [
          { "publisher": "Microsoft Corporation", "title": "Microsoft Visio Professional 2021", "version": "16.0.14332.20481" }
        ]
      }
    }
  ]
}

POST /api/v1/discovery/runs/{runId}/complete

{ "batchCount": 12 }

Rules

• Send raw values. AssetTrove cleans identifiers itself and quietly ignores placeholder serials, so don't filter them out.
• Software mode. FULL is the complete list for that device; anything missing is marked removed when the run completes. DELTA contains only changes, with an optional removed list.
• Retries are safe. Resending a batch with the same idempotency key doesn't create duplicates.
• One bad device doesn't fail the batch. It's skipped and listed in the run's errors, up to 100 examples.

When things go wrong

• Missing batches. If you complete a run with a batch count that doesn't match, AssetTrove lists the missing sequence numbers and keeps the run open so you can resend them.
• A run is already open. You'll get the open run's ID; resume it or cancel it.
• Abandoned runs. A run that receives nothing for 2 hours is cancelled automatically, and a cancelled full run never marks software as removed.

Check the result on the Discovery page or with GET /api/v1/discovery/runs/{runId}: devices matched, created, in conflict, software added and removed, and any errors. A webhook can tell you when a run completes.