Online Help

API Examples Reference

This page collects ready-to-run snippets for the most common AlloyScan API operations. Replace <your-instance>, <id>, <secret>, and any IDs with values from your environment.

Note: Endpoint paths shown below follow common AlloyScan REST conventions. The exact paths, query parameters, and request bodies may vary by release. Confirm against your instance's OpenAPI document before building production integrations.

Get an access token

Every API call needs a bearer token obtained from the OAuth token endpoint.

curl

curl -X POST "https://<your-instance>.alloyservice.com/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<id>" \
  -d "client_secret=<secret>"

PowerShell

$body = @{
  grant_type    = 'client_credentials'
  client_id     = '<id>'
  client_secret = '<secret>'
}

$resp  = Invoke-RestMethod -Method Post `
  -Uri "https://<your-instance>.alloyservice.com/api/oauth/token" `
  -Body $body `
  -ContentType 'application/x-www-form-urlencoded'

$token = $resp.access_token

Sample response

{
  "access_token": "<opaque-bearer-token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Important: Cache the token and reuse it until close to expiry. Each token request counts against your monthly API quota. See Rate Limits.

List devices

Fetch the first page of devices on the current site.

curl

curl -X GET "https://<your-instance>.alloyservice.com/api/v1/devices?limit=50&offset=0" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

PowerShell

$headers = @{ Authorization = "Bearer $token" }

$devices = Invoke-RestMethod -Method Get `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/devices?limit=50&offset=0" `
  -Headers $headers

Get a single device

curl

curl -X GET "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>" \
  -H "Authorization: Bearer <access_token>"

PowerShell

$device = Invoke-RestMethod -Method Get `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>" `
  -Headers $headers

Update a device (PATCH)

PATCH support was added in release 25.7. Use it to update only the fields you intend to change.

curl

curl -X PATCH "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assetTag": "ASSET-0427",
    "customFields": { "owner": "ivan.s" }
  }'

PowerShell

$payload = @{
  assetTag     = 'ASSET-0427'
  customFields = @{ owner = 'ivan.s' }
} | ConvertTo-Json

Invoke-RestMethod -Method Patch `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body $payload

Tag a device

Apply an existing tag from the site's Tag catalog to a device.

curl

curl -X POST "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>/tags" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "tagId": "<tag-id>" }'

PowerShell

$payload = @{ tagId = '<tag-id>' } | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>/tags" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body $payload

Detach a tag from a device

curl

curl -X DELETE "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>/tags/<tag-id>" \
  -H "Authorization: Bearer <access_token>"

PowerShell

Invoke-RestMethod -Method Delete `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/devices/<device-id>/tags/<tag-id>" `
  -Headers $headers

List segments

curl

curl -X GET "https://<your-instance>.alloyservice.com/api/v1/segments" \
  -H "Authorization: Bearer <access_token>"

PowerShell

$segments = Invoke-RestMethod -Method Get `
  -Uri "https://<your-instance>.alloyservice.com/api/v1/segments" `
  -Headers $headers

Handle a 429 response

Both shells return a non-success status when the workload limit fires. Handle it with a short backoff:

PowerShell

function Invoke-AlloyApi {
  param([string]$Method, [string]$Uri, [hashtable]$Headers, $Body, [string]$ContentType)
  for ($attempt = 1; $attempt -le 5; $attempt++) {
    try {
      return Invoke-RestMethod -Method $Method -Uri $Uri -Headers $Headers -Body $Body -ContentType $ContentType
    } catch {
      $status = $_.Exception.Response.StatusCode.value__
      if ($status -eq 429) {
        $retry = [int]($_.Exception.Response.Headers['Retry-After'])
        if (-not $retry) { $retry = [int][Math]::Pow(2, $attempt) }
        Start-Sleep -Seconds $retry
        continue
      }
      throw
    }
  }
}