AgentSlug.com API documentation

This API is alpha version. Not ready for production usage. If you want to start using it, feel free to contact us directly.

Current version: 0.25.1


How to start

To use the API you must be registered on AgentSlug.com. After you are logged in, you can generate you first API token which is used for authorization purposes.

You can use this API for any non-abusive purposes, ajax calls will be accepted by the browser, since we always send Allow-Origin headers. However we discourage you to save your token anywhere public. If API will detect abuse usage of our API, we will disallow further requests or ban whole API for abusive account. Also, there are some limits of requests per day and minute for each registered account.

Basic information

How to send request

If you already have API token you can start right away. For authorization purpoes all requests must contain Authorization: Bearer header. This way our API know who you are and can respond with your resources.

How to process responses

Responses are always json objects (with one exception). For limited requests (like: /tests) there are no need for special logic. However if you extensively requests massive data (e.x. Checks) please save the responses (checks won't change in the future, caching always good) in your database and what's more important try to use pagination (offset) and request least amount of data you need for single requests.

Keep in mind that for every GET request we send resource as object. For example for /tests endpoint we send Tests property with array of Test objects. You should always expect there can be some meta information included as well.

Routes

If there were no limitations, we implemented all routes with standard HTTP methods like:

However for most routes we only implemented GET request for public usage, since there is no much resources you as a user can alter (mostly tests and your account data). There's no need to update executed checks or statistics anyway.

Default error messages

API sometimes responds with error. Unlike route specific errors (e.x. invalid param), errors below won't be specified in route descriptions. All the errors below can occur when requesting any of the routes. With any error, you should expect JSON response body with "msg" field with error explanation.

400 Bad Request
There's something wrong with the request. Most likely you are using query params or POST body in a wrong way. "msg" field should give more information what to do in a human readable style, however sometimes we might fail and if you don't understand the message, please check route specification. And compare your request with examples there.
401 Unauthorized
You are not allowed to make a request to the server. Possibly your token is invalid.
403 Forbidden
Your token is fine, but the resource you're asking for is not meant to be send to you.
404 Not Found
Resource is not found.
500 Internal Server Error
Most likely unexpected error happened to our server. We should notice this in our logs, however if after some time it's not fixed, feel free to contact us by reporting a bug.
503 Service Unavailable
Proxy router cannot find our server. This response can come with invalid JSON (html actually) because of our current proxy implementation.

Public routes description

Below you'll find all the routes which are currently implemented. All finished routes (except those marked as "beta") are finished and specification if changed, will only be extended. If you build request based on this documentation, it should work in the future without any problems.

/tests beta

GET /tests Authentication by: Bearer

Description

Returns all tests which belongs to the authorized user

Request examples

Example curl

-X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests"

Response examples

200 OK

Test resource

{
  "Tests": [
    {
      "testID": "{number} testID",
      "url": "{string} test url",
      "word": "{string} word which test look for",
      "testName": "{string} custom test name",
      "interval": "{number} seconds interval between each tests",
      "sensitivity": "{number} level of sensitivity (5 - medium, 10 - high)",
      "userAgent": "{string} custom User Agent robot sends when request website",
      "allowedRedirects": "{number} 0 - forbidden, 1 - allowed",
      "lastCheck": "{number} UNIX timestamp of last check",
      "active": "{number} 1 test is active, 0 - test is on hold",
      "downtime": "{number} 1 - flagged as down, 0 - no flag",
      "publicHash": "{string|null} - hash for public realtime websites, null if not generated"
    }
  ]
}

POST /tests Authentication by: Bearer

Description

Inserts new test which belongs to the authorized user.

Request examples

Example curl

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"testName": "foo", "url": "http://foo.agentslug.com", "interval": 600, "active": 0}' "https://api.agentslug.com/tests"

Response examples

201 Created

Test resource with testID field only

{
  "Test": {
    "testID": "{number}"
  }
}

/tests/:testID beta

GET /tests/:testID Authentication by: Bearer

Description

Returns one specific test

Request examples

Example curl

-X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests/TEST_ID"

Response examples

200 OK

Test resource

{
  "Test": {
    "checkID": "{number} checkID",
    "testID": "{number} testID",
    "redirect": "{number} check encountered redirection (0 - no, 1 - yes)",
    "code": "{number} HTTP response code",
    "time": "{number} UNIX timestamp",
    "word": "{string} word which was a subject of document search",
    "status": "{number} status of check (0 - failed, 1 - passed)",
    "checkerID": "{string} ID of server which proceeded the test",
    "total_time": "{number} total time of check (in seconds)",
    "namelookup_time": "{number} time spent on resolving the name (in seconds)",
    "connect_time": "{number} time spent on connecting the remote host (in seconds)",
    "pretransfer_time": "{number} time to file transfer was about to begin",
    "starttransfer_time": "{number} time to receive the very first byte",
    "document_length": "{number} string length of received content (including headers)"
  }
}

PATCH /tests/:testID Authentication by: Bearer

Description

Updates specific test. Fields which can be updated are: url, word, interval, sensitivity, userAgent, allowedRedirects.

Request examples

Example curl

curl -X PATCH -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"url": "https://agentslug.com"}' "https://api.agentslug.com/tests/TEST_ID"

Response examples

200 OK

Default msg

{
  "msg": "Updated"
}

400 Bad Request

Something is wrong with requested update data

{
  "msg": "url not valid web url"
}

DELETE /tests/:testID Authentication by: Bearer

Description

Deletes specific test. When route response with HTTP 202 Accepted, it means test being removed and won`t be visible in any API routes any more.

Request examples

Example curl

curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" "https://api.agentslug.com/tests/TEST_ID"

Response examples

202 Accepted

Request is accepted, test is being deleted.

{
  "msg": "Accepted"
}

/tests/:testID/lastChecks beta

GET /tests/:testID/lastChecks Authentication by: Bearer

Description

Returns executed checks of test. This endpoint have some limits. Because we aggregate checks statistics in a different storage for performance reasons, we don't store all checks which were executed forever. After some time we remove them from our database. This is why it's forbidden to query this endpoint for checks older than 30 days. Also, keep in mind this endpoint is very fragile and slow. Only use it if really need it. However, for most purposes, /tests/:testID/stats endpoint will give you enough information you need without above limitations.

Query

Following params can be set as GET params

limit
{number} maximum number of items for each response (as in SQL). Maximum possible number is 1000.
offset
{number} how many items should be skipped during search (as in SQL).
sort
{string} - sort by (possible values: 'asc' - ascending, 'desc' - descending).
youngest
{number} UNIX timestamp of the youngest queried check.
oldest
{number} UNIX timestamp of the oldest queried check (please keep in mind the maximum days limit of 30.)

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests/TEST_ID/lastChecks?limit=1"

Response examples

200 OK

Array of Checks

{
  "Checks": [
    {
      "checkID": "{number} checkID",
      "testID": "{number} testID",
      "redirect": "{number} check encountered redirection (0 - no, 1 - yes)",
      "code": "{number} HTTP response code",
      "time": "{number} UNIX timestamp",
      "word": "{string} word which was a subject of document search",
      "status": "{number} status of check (0 - failed, 1 - passed)",
      "checkerID": "{string} ID of server which proceeded the test",
      "total_time": "{number} total time of check (in seconds)",
      "namelookup_time": "{number} time spent on resolving the name (in seconds)",
      "connect_time": "{number} time spent on connecting the remote host (in seconds)",
      "pretransfer_time": "{number} time to file transfer was about to begin",
      "starttransfer_time": "{number} time to receive the very first byte",
      "document_length": "{number} string length of received content (including headers)"
    }
  ]
}

/tests/:testID/downtimes beta

GET /tests/:testID/downtimes Authentication by: Bearer

Description

Returns downtimes information for test.

Query

Following params can be set as GET params

youngest
{number} UNIX timestamp of the youngest (downtimeFrom) queried downtimes object.
oldest
{number} UNIX timestamp of the oldest (downtimeFrom) queried downtimes object.

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests/TEST_ID/downtimes?youngest=UNIX_TIMESTAMP"

Response examples

200 OK

Array of Downtimes

{
  "Downtimes": [
    {
      "downtimeID": "{number} - internal unique",
      "testID": "{number} testID",
      "downtimeFrom": "{number} first downtime report timestamp",
      "downtimeTo": "{number} timestamp of test uptime recognition",
      "checkID": "{number} ID of a check which first recognized downtime",
      "checkerID": "{string} checkID server ID",
      "checkIDClose": "{number} ID of uptime confirmation check",
      "checkerIDClose": "{number} ID of a server which confirmed uptime"
    }
  ]
}

/tests/:testID/stats beta

GET /tests/:testID/stats Authentication by: Bearer

Description

Returns aggregated checks statistics for test. Statistics are generated in hourly interval for each robot. For example, if robot X did 10 checks during last hour, and robot Y did 6 checks this endpoint will return two objects with summarized stats for each of them.

Query

Following params can be set as GET params

limit
{number} maximum number of items for each response (as in SQL). Maximum possible number is 50000.
offset
{number} how many items should be skipped during search (as in SQL).
sort
{string} - sort by (possible values: 'asc' - ascending, 'desc' - descending).
youngest
{number} UNIX timestamp of the youngest queried stats object.
oldest
{number} UNIX timestamp of the oldest queried stats object.

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests/TEST_ID/stats?limit=1"

Response examples

200 OK

Array of Stats

{
  "Stats": [
    {
      "testID": "{number} - testID",
      "timeFrom": "{number} UNIX timestamp of first second of the hour (e.x. 14:00:00)",
      "timeTo": "{number} UNIX timestamp of last second the the hour (e.x. 14:59:59)",
      "checksCount": "{number} number of checks being executed for the checkerID between timeFrom and timeTo",
      "totalTime": "{number} sum of total times of connections proceeded during checks (e.x. to get average you need to totalTime/checksCount)",
      "documentLength": "{number} sum of document lengths for responses gathered during checks (average: documentLength/checksCount)",
      "checkerID": "{string} ID of the checker robot"
    }
  ]
}

/tests/:testID/publicHash beta

POST /tests/:testID/publicHash Authentication by: Bearer

Description

Creates new public hash for test. Public hash is used for sharing the test result for public. There can be only one public hash per test (each POST request will regenerate it).

Request examples

Example curl

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/tests/TEST_ID/publicHash"

Response examples

200 OK

New hash

{
  "publicHash": "NEWLY_CREATED_HASH"
}

/auth/tokens beta

GET /auth/tokens Authentication by: Bearer

Description

Returns all generated tokens associated with authenticated account.

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/auth/tokens"

Response examples

200 OK

Array of Tokens

{
  "Tokens": [
    {
      "token": "{string} token",
      "expire": "{string} expiration datetime"
    }
  ]
}

POST /auth/tokens Authentication by: login/password

Description

Creates new token for authenticated account.

Request examples

Example curl

curl -X POST -H "Content-Type: application/json" -d '{"login":"YOUR_EMAIL", "password": "YOUR_PASSWORD"}' "https://api.agentslug.com/auth/tokens"

Response examples

201 CREATED

New token is created and returned with the body.

{
  "Token": {
    "token": "{string} token",
    "expire": "{string} expiration datetime"
  }
}

/auth/tokens/:tokenID beta

DELETE /auth/tokens/:tokenID Authentication by: Bearer

Description

Deletes token

Request examples

Example curl

curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" "https://api.agentslug.com/auth/tokens/TOKEN_FOR_DELETION"

Response examples

200 OK

Token deleted. Futher authentication attempts will be rejected

{
  "msg": "Deleted"
}

/checks beta

GET /checks Authentication by: Bearer

Description

Returns executed checks of authenticated user. This endpoint have some limits. Because we aggregate checks statistics in a different storage for performance reasons, we don't store all checks which were executed forever. After some time we remove them from our database. This is why it's forbidden to query this endpoint for checks older than 30 days. Also, keep in mind this endpoint is very fragile and slow. Only use it if really need it. However, for most purposes, /tests/:testID/stats endpoint will give you enough information you need without above limitations.

Query

Following params can be set as GET params

limit
{number} maximum number of items for each response (as in SQL). Maximum possible number is 1000.
offset
{number} how many items should be skipped during search (as in SQL).
sort
{string} - sort by (possible values: 'asc' - ascending, 'desc' - descending).
youngest
{number} UNIX timestamp of the youngest queried check.
oldest
{number} UNIX timestamp of the oldest queried check (please keep in mind the maximum days limit of 30.)

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/checks?oldest=1472680488"

Response examples

200 OK

Array of checks

{
  "Checks": [
    {
      "checkID": "{number} checkID",
      "testID": "{number} testID",
      "redirect": "{number} check encountered redirection (0 - no, 1 - yes)",
      "code": "{number} HTTP response code",
      "time": "{number} UNIX timestamp",
      "word": "{string} word which was a subject of document search",
      "status": "{number} status of check (0 - failed, 1 - passed)",
      "checkerID": "{string} ID of server which proceeded the test",
      "total_time": "{number} total time of check (in seconds)",
      "namelookup_time": "{number} time spent on resolving the name (in seconds)",
      "connect_time": "{number} time spent on connecting the remote host (in seconds)",
      "pretransfer_time": "{number} time to file transfer was about to begin",
      "starttransfer_time": "{number} time to receive the very first byte",
      "document_length": "{number} string length of received content (including headers)"
    }
  ]
}

/account beta

GET /account Authentication by: Bearer

Description

Returns basic account information of authorized user.

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/account"

Response examples

200 OK

Account related informations

{
  "User": {
    "email": "{string} user's email",
    "logged": "{string} datetime (UTC) of last active login action (passed login and password on web app)",
    "tz": "{string} timezone set as account preference (e.x Europe/Warsaw)",
    "points": "{number} number of available points"
  }
}

/account/apiUsage beta

GET /account/apiUsage Authentication by: Bearer

Description

Returns current accounts's api usage limits (rates).

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/account/apiUsage"

Response examples

200 OK

Api usage information

{
  "apiUsage": {
    "dailyUsage": "{number} number of requests made today",
    "dailyLimit": "{number} daily limit",
    "monthlyUsage": "{number} number of requests made this month",
    "monthlyLimit": "{number} monthly limit"
  }
}

/account/billing beta

GET /account/billing Authentication by: Bearer

Description

Returns billing for current month or requested one. Billing is the detailed usage information for each hour.

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/account/billing?year=2017&month=05"

Response examples

200 OK

Billing - detailed usage information

{
  "apiUsage": {
    "charged": "{bool} true when billing period is charged and won't change",
    "date": "{number} start of the billing period (one hour)",
    "amount": "{number} amount charged",
    "currency": "{string} currency code",
    "type": "{string} billing subject (uptimeTest|contentTest...) ",
    "value": "{number} units charged (e.x. on uptimeTest check is one unit)"
  }
}

/account/email beta

PUT /account/email Authentication by: Bearer

Description

Starts procedure for changing the account's email address. When request is accepted, the email candidate is stored and needs to be confirmed either by opening the link sent via e-mail to a new e-mail address or via API using POST /account/email endpoint.

Important: The confirmation token is sent only to a new email address. Finishing the procedure might lead to session invalidation on some of the web applications.

This endpoint required authentication, hence we consider it safe. Additionally we would send a informative message to the old e-mail address.

Request examples

Example curl

curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"email":"YOUR_NEW_EMAIL"}' "https://api.agentslug.com/account/email"

Response examples

201 CREATED

{
  "msg": "Procedure started"
}

POST /account/email Authentication by: Bearer

Description

Confirms the email changing procedure.

Request examples

Example curl

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"token":"TOKEN_FROM_EMAIL_MESSAGE"}' "https://api.agentslug.com/account/email"

Response examples

200 OK

{
  "msg": "Email changed"
}

/account/password beta

PUT /account/password Authentication by: Bearer

Description

Starts procedure for changing the account's password. For more information, please refer to /account/email section.

Request examples

Example curl

curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"password":"YOUR_NEW_PASSWORD"}' "https://api.agentslug.com/account/password"

Response examples

201 CREATED

{
  "msg": "Procedure started"
}

POST /account/password Authentication by: Bearer

Description

Confirms the password changing procedure.

Request examples

Example curl

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"token":"TOKEN_FROM_EMAIL_MESSAGE"}' "https://api.agentslug.com/account/password"

Response examples

200 OK

{
  "msg": "Password changed"
}

/account/invoiceInfo beta

GET /account/invoiceInfo Authentication by: Bearer

Description

Gets account invoice information

Request examples

Example curl

curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://api.agentslug.com/account/invoiceInfo"

Response examples

200 OK

{
  "InvoiceInfo": {
    "vat": "PL-666666666",
    "name": "FooCorp",
    "address": "Street 1/2",
    "city": "CityName",
    "postal": "00-001",
    "country": "Germany",
    "countryType": "EU"
  }
}

PUT /account/invoiceInfo Authentication by: Bearer

Description

Replaces account invoice information

Request examples

Example curl

curl -X PUT https://api.agentslug.com/account/invoiceInfo -H 'authorization: Bearer YOUR_TOKEN' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{"vat": "PL-666666666","name": "FooCorp","address": "Street 1/2","city": "CityName","postal": "00-001","country": "Germany","countryType": "EU"}'

Response examples

200 OK

{
  "msg": "Updated!"
}