Simple Example

Let's begin with an example. Assume we want to create a simple ping measurement from 50 probes anywhere in the world to ripe.net.

Here's how to do this in cURL (in UNIX shell):

curl --location 'https://atlas.ripe.net/api/v2/measurements/' \
--header 'Authorization: Key ********-****-****-****-************' \
--data '{
  "definitions": [
    {
      "target": "ripe.net",
      "description": "My First Measurement",
      "type": "ping",
      "af": 4
    }
  ],
  "probes": [
    {
      "requested": 5,
      "type": "area",
      "value": "WW"
    }
  ]
}'

If you're a Windows user you will probably need to escape the JSON string in the cURL command.

This is what it looks like in Postman:

Response

If you have filled out everything correctly, you will get a response like this:

{"measurements": [<SOME_MEASUREMENT_ID>]}

If you didn't use the right key, or no key at all, you will get an error:

{"error":{"status":403,"code":104,"detail":"Authentication credentials were not provided.","title":"Forbidden"}}

In this case, you may want to check keys documentation (opens new window).

If you made a mistake in the entry of the payload, you will get the following error:

{
  "error": {
    "status": 400,
    "code": 104,
    "detail": "Invalid input. Please check the documentation.",
    "title": "Bad Request"
  }
}

In this case, check your entry carefully and try again.

Now let's take a look at our request in more detail.

The Payload for the POST Request

Let's take another look at the payload we sent with the POST request:

{
  "definitions": [
    {
      "target": "ripe.net",
      "description": "My First Measurement",
      "type": "ping",
      "af": 4
    }
  ],
  "probes": [
    {
      "requested": 50,
      "type": "area",
      "value": "WW"
    }
  ]
}

Basically, each request has two objects: definitions and probes, along with some general fields that apply to all measurement definitions in the request. In our example we didn't use any of those general fields.

In the next sections we will discuss these objects and fields.