RESTful API Documentation

This is a lightweight and secure RESTful / HTTP-based API for writing to and reading from the metricsmine Platform.

Getting started

General format

Our API follows a basic RESTful design. You are required to provide an authentication token (see 'Authentication' below) with each request. All requests are returned in strict JSON format. XML is not supported.

We make changes to the APIs from time to time. For more information, see API Changes.

Endpoints are documented with the HTTP method for the request and a partial resource identifier.
Curly braces, {}, indicate values you have to supply. Example:

GET /api/{public_token}/echo.json

Prepend your metricsmine URL to the resource identifier to get the full endpoint URL:

https://({code}|api).metricsmine.com/api/{public_token}/echo.json

The examples in the docs are cURL statements. You can run the statements on a command line to try out different API requests. Example:

curl -H 'X-Auth-Token: {private_token}' -H 'Content-Type: application/json'
-X POST https://api.metricsmine.com/api/{public_token}/echo -d '{"message": "test"}'

Security and Authentication

This is an SSL-only API, regardless of how your account is configured.

API tokens are managed in the Admin panel at Account Settings > API.

metricsmine

Supply your private authentication token in the X-Auth-Token header:

curl -H 'X-Auth-Token: {private_token}' <endpoint>

When you transmit an access token header through HTTPS, then nobody apart from you, the client, will be able to see this token as the request will be tunneled through a secure connection.


Sending Data

After successfully authenticating your connection, you may submit metrics and events to the server.

Request Format

You must supply a Content-Type: application/json or Content-Type: application/x-www-form-urlencoded header in PUT and POST requests.

Rate Limits

This API is rate limited. We only allow a certain number of requests per minute depending on your plan and the endpoint.
We reserve the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients.

Response Format

The API responds to successful requests with HTTP status codes in the 200 or 400/500 range.
When you create or update a resource, metricsmine renders the resulting JSON representation in the response body. Example:

Status: 200 OK
{
    "success": true,
    "echo": {
        "id_account": 89237237,
        "params": {
            "api": "8a3034c70b6bb049"
        },
        "get": [],
    }
}

All time values returned by the API are expressed UTC time and are formatted as ISO 8601 strings. YYYY-MM-DD HH:MM:SS format.
Some endpoints use Unix time, also known as Epoch or POSIX time. Example: 1451323491.


Collectd

You can read more about Collectd here. Get system metrics like CPU, Load, Disk and Network I/O for all of your hosts.

<Plugin write_http>
<URL "https://api.metricsmine.com/api/{public_token}/agents/collectd">
    User "{account_code}"
    Password "{private_token}"
    VerifyPeer false
    VerifyHost false
    CACert "/etc/ssl/ca.crt"
    Format "JSON"
</URL>
</Plugin>

Endpoints

Metrics

Metrics are custom measurements stored in metricsmine's Metrics Platform.

GET /api/{readonly_token}/metrics.json
curl https://api.metricsmine.com/api/{readonly_token}/metrics.json
GET /api/{readonly_token}/metrics/{metric_name}
curl https://api.metricsmine.com/api/{readonly_token}/metrics/df-percent-bytes-free
POST /api/{public_token}/metrics/{metric_name}(/{instance}|/{value}).json
FieldData typeDescription
metricstring
instance optionalstring
time optionaldatetime
unique optionalstring
valuedouble
unit_type optionalstring
unit optionalstring
curl -H 'X-Auth-Token: {private_token}' -X POST https://api.metricsmine.com/api/{public_token}/metrics/df-percent-bytes-free/server-01/23.json
curl -H 'X-Auth-Token: {private_token}' -H 'Content-Type: application/json' -X POST https://api.metricsmine.com/api/{public_token}/metrics/df-percent-bytes-free/server-01.json -d '{"value": 23, "unit_type": "int"}'
curl -H 'X-Auth-Token: {private_token}' -H 'Content-Type: application/json' -X POST https://api.metricsmine.com/api/{public_token}/metrics/first-test/default/1 -d '{"unit_type": "int"}'

PHP Examples

file_get_contents(
   'https://api.metricsmine.com/api/{public_token}/metrics/' . implode('/', array(
        {metric_name}, ('default'|{instance}), {value}
    )) . '/'
    , false
    , stream_context_create(array(
    'http' => array(
            'method' => 'POST',
            'header' => implode("\r\n", array(
                'X-Auth-Token: {private_token}',
                'Content-type: application/x-www-form-urlencoded',
            )),
            'content' => http_build_query(
            array(
                'value' => {value}, // not mandatory
                'unit_type' => 'num', // not mandatory
                'unit' => 'EUR', // not mandatory
                'time' => '2015-12-03 22:32:03', // not mandatory
                )
            ),
            'timeout' => 3,
        ),
    )
));
file_get_contents(
    'https://api.metricsmine.com/api/{public_token}/metrics/' . implode('/', array(
        {metric_name}, {instance}, {value}
    )) . '/'
    , false
    , stream_context_create(array(
    'http' => array(
            'method' => 'POST',
            'header' => implode("\r\n", array(
                'X-Auth-Token: {private_token}',
                'Content-type: application/json',
            )),
            'timeout' => 3,
        ),
    )
));

Instances

GET /api/{readonly_token}/instances.json
curl https://api.metricsmine.com/api/{readonly_token}/instances.json

Events

POST /api/{public_token}/logs/{service}/{instance}
FieldData typeDescription
servicestringThe type of service, i.e. "php", "tickets" or "symfony"
instance optionalstringThe name of the environment where the event occurred. i.e. "server-01" oe "car-203ACV"
typestring The type or severity of this event, i.e. "problem", "error", "fatal" or "info".
Recommended values of standard types debug info warning error critical alert
time optionaldatetimeThe time the event occurred
messagestringThe content of event
file optionalstring
line optionalinteger
url optionalstring
curl -H 'X-Auth-Token: {private_token}' -H 'Content-Type: application/json' -X POST https://api.metricsmine.com/api/{public_token}/logs/:service/(:instance|default) -d '{"type": "int"}'
Using Monolog

You can send PHP logs to metricsmine using the Monolog library. We will automatically parse the JSON format allowing you to quickly drill down into issues.

POST /api/{public_token}/logs/monolog/{service}

Troubleshooting HTTP

Wait a Few Minutes

Wait a few minutes after sending an event to give it time to index and appear in the search results.
It normally happens within seconds, but sometimes it can take longer.

Check Content Type in Header

Check to make sure you are using the right contentType in header.
By default metricsmine assumes the contentType of application/x-www-form-urlencoded. You can set contentType in your header to application/json to convert data to JSON automatically.

Test Sending Data

You can POST an event to metricsmine using our HTTPS endpoint.

curl -H 'X-Auth-Token: {private_token}' -H 'Content-Type: application/json'
-X POST https://api.metricsmine.com/api/{public_token}/echo -d '{"message": "test"}'

Check Response Status Code

You can check your HTTP response code from Status Code

metricsmine doesn’t parse or analyze requests all at once, so we only use the following response codes:

CodeDescription
200 (OK)The request data was accepted and will be processed asynchronously.
This doesn’t imply that your data was valid, just that it was enqueued to be processed.
401 (Unauthorized)The request has not been applied because it lacks valid authentication credentials for the endpoint resource.
Provide header credentials for authentication.
404 (Not Found)
405 (Method Not Allowed)A request method is not supported for the requested resource.
500 (Internal Server Error)There was an internal error processing your request. If the description is a timeout, you can try again.