Read / query contract

Use PMT results from PowerShell, CLI or another application.

The webapp is the normal human-facing view.

Use the egress API when you need to query, filter, count, export or integrate authorised stored results.

The same read contract powers the PMT webapp.

Authentication

tkn is always a list, even for one token.

{
  "tkn": ["YOUR_READ_TOKEN"],
  "pin": "YOUR_PIN"
}

A request may include up to 50 tokens. key is an alias for pin.

All supplied tokens are checked using the single supplied PIN. One invalid token currently causes the whole request to fail with HTTP 403.

Basic PowerShell query

$body = @{
    tkn = @($env:PMT_READ_TOKEN)
    pin = $env:PMT_PIN
} | ConvertTo-Json

$result = Invoke-RestMethod `
    -Method Post `
    -Uri "https://egress.pmtapi.net/egress/v3/query?flat=true" `
    -ContentType "application/json" `
    -Body $body

Then work with ordinary PowerShell objects:

$result | Where-Object val -eq -3
$result | Sort-Object stn, sens
$result | Export-Csv .\pmt-results.csv -NoTypeInformation

Flat and wrapped responses

?flat=true is the default and returns the raw docs list.

?flat=false returns a wrapper with docs plus metadata such as query_ts, count and invalid_tokens.

Only flat is accepted as a URL query parameter. Unknown URL or body fields are rejected with 422.

Core query fields

Required: tkn list, maximum 50 tokens.

Query modes

Use one latest mode at a time. Requests enabling more than one latest mode are rejected with 422.

LATEST N / HISTORY

{
  "tkn": ["YOUR_READ_TOKEN"],
  "stn": "server-01",
  "sens": "backup_result",
  "latest_n": 100
}

The webapp uses latest_n=100 for recent history.

latest_n accepts 1–1000.

Incremental reads

since is a strict > cutoff on PMT server time ts; it is not a query against a stored query_ts field.

Wrapped responses include a pre-scan query_ts. A polling client should use an overlap where boundary safety matters and deduplicate any repeated rows.

The current webapp schedules 30-second incremental refreshes and uses the pre-scan query_ts minus one second as its next since.

Server time versus measurement time

ts is PMT server processing time. tc is measurement/source reading time.

since_ts takes precedence over since. since_tc can add a measurement-time cutoff alongside the server-time filter.

Use numeric display offsets when a local display timezone is required. Epoch output is timezone-independent.

PowerShell: find exceptions

$body = @{
    tkn        = @($env:PMT_READ_TOKEN)
    pin        = $env:PMT_PIN
    latest_stn = $true
} | ConvertTo-Json

$result = Invoke-RestMethod `
    -Method Post `
    -Uri "https://egress.pmtapi.net/egress/v3/query?flat=true" `
    -ContentType "application/json" `
    -Body $body

$result |
    Where-Object val -eq -3 |
    Select-Object stn, sens, val, ts, tc

Temporary ASK export

$body = @{
    tkn  = @($env:PMT_READ_TOKEN)
    pin  = $env:PMT_PIN
    sens = "free_disk_gb"
} | ConvertTo-Json

Invoke-RestMethod `
    -Method Post `
    -Uri "https://egress.pmtapi.net/egress/v3/query?flat=true" `
    -ContentType "application/json" `
    -Body $body |
    Sort-Object val |
    Export-Csv .\free-disk-results.csv -NoTypeInformation

PMT tells you which sources answered. It does not know the authoritative list of systems that were expected to answer.

Multi-token queries

{
  "tkn": [
    "READ_TOKEN_A",
    "READ_TOKEN_B"
  ],
  "pin": "SHARED_PIN"
}

This can combine authorised results without merging the underlying projects.

Current behaviour:

• one PIN is supplied for the whole request;
• every token must validate against it;
• one invalid token causes HTTP 403 for the whole request.

If projects use different PINs, query them separately or use an access arrangement appropriate to the intended combined view.