Scout API

API Quick Start

API Ground Rules

HTTP Verbs

Scout's API conforms to standard HTTP verbs where possible:

GET Used for retrieving resources.
POST Used for creating resources or performing custom actions. Example: adding roles to a server
PATCH Used for partially updating resources with one or more fields. While PATCH is preferred for these cases, endpoints will also accept POST requests.
DELETE Used for deleting resources.

HTTP Return Codes

HTTP 200 OK The request succeeded.
HTTP 404 Not Found A resource you have specified can't be found. The most common cause is a bad hostname.
HTTP 422 Unprocessable Entity The resource is found, but there's something wrong with the parameters you've provided.

JSON Result Hash

Every endpoint returns a JSON hash. The hash will have a message field at a minimum. If the endpoint returns results, it will be under a results field:

{"message":"See here for error messages, etc.", "results":"these are the results you're looking for."}


Scout uses key-based authentication. The key must be included with every request as a part of the base URL:

You already have one API key that is the same as your account key. You can add and remove API keys at any time. If you are using an API key in a 3rd-party application, we recommend creating a separate key — distinct from your account key — in case you need to de-authorize it later.

Fetch Alerts




  "id": 999999,
  "time": "2012-03-05T15:36:51Z",
  "server_name": "Blade",
  "server_hostname": "blade",
  "lifecycle": "start", // can be [start|end|oneoff]  -- "oneoff" is for alerts generated internally by plugins
  "title": "Last minute met or exceeded 3.00 , increasing to 3.50 at 01:06AM",
  "plugin_name": "Load Average",
  "metric_name": "last_minute", // will be nil for alerts generated internally by plugins
  "metric_value": 3.5, // will be nil for alerts generated internally by plugins
  "url": "",

This endpoint will return up to 50 alerts created within the last 30 days.

Add Roles

curl -X POST --data "roles=role1,role2"



For each role:


Enable/Disable Notifications on a Server

curl -X POST --data "notifications=[true|false]"



Delete a Server

curl -X DELETE



Add a Marker

Markers appear on charts. Use them to note significant events like production deploys, performance enhancements, etc. Example:

curl -X POST --data "notes=your text"



Need Something More?

If there's something not listed here you would like to do with the API, send us a message at