Scoutmon REST API

The Scoutmon API lets you read and manage your IT assets, users, vendors, and locations programmatically. All endpoints are scoped to your company — you can only access data that belongs to your account.

All requests and responses use JSON. Timestamps are ISO 8601 in UTC. UUIDs are used for all resource identifiers.

Authentication

The API uses Bearer token authentication via API keys. Generate an API key from your Settings → API Keys page.

Pass your key in the Authorization header on every request:

# Replace sk_... with your actual API key
curl https://scoutmon.com/api/assets \
  -H "Authorization: Bearer sk_your_api_key_here"

API Key format

Keys follow the format sk_ followed by 56 hex characters. The first 10 characters form the key prefix used for rate limiting.

Scopes

Each API key has one or more scopes. Request the minimum scope needed for your integration.

What API keys can't do

Keys are for working with your asset data. Anything that changes who can get into your account needs a person signed in to Scoutmon, so these return 403 with "code": "api_key_not_allowed" even for a write key:

• inviting, changing or removing users, and changing permissions
• creating or revoking API keys
• creating, changing or deleting webhooks (listing them is fine)
• changing company settings

Expiry

When you create a key you choose when it expires: 30, 90, 180 or 365 days, or never. An expired key, or a key whose creator has been deactivated, returns 401.

Rate Limits

Rate limits are applied per API key. If you exceed a limit, requests return 429 Too Many Requests.

After the limit resets, requests proceed normally. For bulk operations, use the limit and offset query parameters to page through results rather than fetching everything repeatedly.

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an error field describing what went wrong.

{
  "error": "Asset not found"
}

Pagination & Filtering

All list endpoints support limit and offset for pagination, plus endpoint-specific filter parameters. The total count of matching records is returned in the X-Total-Count response header.

Common query parameters

Example — paginate through assets

# Page 1
curl "https://scoutmon.com/api/assets?limit=50&offset=0" \
  -H "Authorization: Bearer sk_..."

# Page 2
curl "https://scoutmon.com/api/assets?limit=50&offset=50" \
  -H "Authorization: Bearer sk_..."

The X-Total-Count header tells you how many records match the current filter, so you can compute the number of pages as Math.ceil(total / limit).

Assets

curl "https://scoutmon.com/api/assets?status=checked-out&sort_by=name&sort_dir=asc&limit=25" \
  -H "Authorization: Bearer sk_..."

[
  {
    "id": "a1b2c3d4-...",
    "asset_tag": "IT-0042",
    "name": "MacBook Pro 16\"",
    "category": "Laptop",
    "status": "checked-out",
    "value": "2499.00",
    "location_name": "Sydney HQ",
    "vendor_name": "Apple Inc.",
    "assigned_user_name": "Alice Smith",
    "created_at": "2025-11-01T09:00:00.000Z"
  }
]

Users

curl "https://scoutmon.com/api/users?role=admin" \
  -H "Authorization: Bearer sk_..."

[
  {
    "id": "u1b2c3d4-...",
    "name": "Alice Smith",
    "email": "[email protected]",
    "role": "admin",
    "status": "active",
    "department": "Engineering",
    "last_login": "2026-03-28T14:22:00.000Z",
    "created_at": "2025-09-01T08:00:00.000Z"
  }
]

Vendors

Locations

[
  {
    "id": "loc1b2c3-...",
    "name": "Sydney HQ",
    "type": "Office",
    "address": "123 Pitt St, Sydney NSW 2000",
    "lat": -33.8688,
    "lng": 151.2093
  }
]

Webhooks

Webhooks send an HTTPS POST to your endpoint when something happens. Set them up in Settings → Webhooks (a signed-in admin is needed; API keys can list them but not change them).

Events

{
  "event": "asset.checked_out",
  "delivered_at": "2026-10-05T03:12:44.120Z",
  "data": { … }
}

Verifying the signature

Each request carries X-Scoutmon-Event and X-Scoutmon-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body using your webhook's secret (shown once, when you create it). Compute the same HMAC over the exact bytes you received and compare in constant time.

// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-scoutmon-signature']));

Delivery

Endpoints must be public https:// addresses; private and internal addresses are refused, and redirects aren't followed. Each event is attempted once, with an 8-second timeout. The last response status is shown against the webhook in Settings, and Send test sends a signed ping. There are no automatic retries yet, so use the daily events or the API to reconcile if your endpoint was down.

Search

curl "https://scoutmon.com/api/search?q=macbook" \
  -H "Authorization: Bearer sk_..."

{
  "assets": [
    { "id": "...", "name": "MacBook Pro 16\"", "asset_tag": "IT-0042", "category": "Laptop", "status": "checked-out" }
  ],
  "users": [],
  "vendors": []
}